CPU Interaction & Execution Model

Overview

guideXOS directly programs x86-64 CPU structures: GDT, IDT, TSS, paging (PML4), control registers (CR3/CR2), and APIC/LAPIC for interrupts and timers. Most of the low-level setup occurs in EntryPoint and subsequent kernel initialization calls.

---

Privilege Rings

The kernel configures both Ring 0 (kernel) and Ring 3 (user) code/data segments in the GDT. Current builds still execute application logic in kernel context; user-mode transition is stubbed. Planned progression:

• Ring 0: All current code paths (drivers, GUI, loader, network stack)
• Ring 3: Defined selectors (UserCodeSelector/UserDataSelector), not yet entered
• RPL: GDT sets user segment descriptors with DPL=3 for future isolation

---

Global Descriptor Table (GDT) & TSS

Implementation: Kernel/Misc/GDT.cs. Descriptors created for kernel/user code & data plus a 64-bit TSS entry. The TSS holds privilege stack (RSP0) used when CPU transitions from Ring 3 -> Ring 0 on interrupts.

KernelCodeSelector = 0x08
KernelDataSelector = 0x10
UserCodeSelector   = 0x1B (0x18 | 3)
UserDataSelector   = 0x23 (0x20 | 3)
TssSelector        = 0x28
                    

The TSS is populated and IO bitmap disabled for user mode (future). SetKernelStack() updates RSP0 before user transitions.

---

Interrupt Descriptor Table (IDT) & Flow

Implementation: Kernel/Misc/IDT.cs. 256 entries are prepared, native assembly sets handler addresses, then Native.Load_IDT() loads IDTR. Interrupt handler export intr_handler processes:

1. CPU exception decode (vectors < 0x20)
2. System call (vector 0x80) dispatch via API.HandleSystemCall()
3. Timer tick (0x20) -> scheduler + ThreadPool.Schedule()
4. Driver-specific IRQ forwarding (Interrupts.HandleInterrupt())
5. EOI signaling via PIC/APIC (Interrupts.EndOfInterrupt())

User software interrupts can be enabled per vector using IDT.AllowUserSoftwareInterrupt() (sets gate DPL=3).

---

Paging Model

Implementation: Kernel/Misc/PageTable.cs. Identity maps 0x1000 .. 4 GiB (4KiB pages). Functions:

• Initialise() sets CR3 to shared PML4
• Map()/MapUser() assign PTEs with present|rw|(user)
• GetPageUser() path prepares user-accessible entries (sets U bit)

All allocations are physical + identity mapped; future address space isolation will introduce per-process PML4 cloning (see AddressSpace scaffold).

---

System Calls (int 0x80)

System calls are initiated via software interrupt 0x80 (once user mode exists). Current path:

intr_handler()
  if irq == 0x80:
     pCell = RCX (method fixup)
     name  = module name
     RAX   = API.HandleSystemCall(name)
                    

Call convention: Parameters marshalled manually; return value in RAX.

---

User Mode Stub & Planned Transition

File: UserModeStub.cs exports iret_to_user() as a placeholder. Real implementation will set up stack frame and execute iretq with:

RIP = entry
CS  = UserCodeSelector | RPL=3
RFLAGS = IF=1
RSP = user stack top
SS  = UserDataSelector | RPL=3
                    

Invocation: SchedulerExtensions.EnterUserMode(rip, rsp).

---

Executable Loading (GXM)

File: GXMLoader.cs. Steps:

1. Validate header magic (GXM\0 or MUE\0)
2. Allocate aligned region for image
3. Identity map pages with MapUser() (preparing for future ring-3)
4. Allocate & map user stack (64 KiB)
5. Call SchedulerExtensions.EnterUserMode() (currently logs stub)

Supports GUI script preface for dynamic window creation (no native execution).

---

Multi-core (SMP)

File: SMP.cs. Bootstrap CPU (ID=0) initializes global structures, copies trampoline, sends INIT + STARTUP IPIs to APs. Each AP:

• Enables SSE
• Starts Local APIC timer
• Initializes ThreadPool (shared structures)
• Enters idle halt loop

Shared structures: GDT, IDT, PageTable root at fixed physical addresses in low memory block.

---

Roadmap / Next Steps

• Implement real iret_to_user assembly stub and TSS ltr
• Per-process address space: copy kernel PML4 slots only
• System call ABI formalization (register usage, error codes)
• User-land exception handling and signal model
• Scheduler: separate kernel vs user threads
• Security: validate user pointers, restrict IO port access

---

Related Topics