x86 OS development using Bochs emulator (x86osdev)

Prerequisites: You need to know x86 assembly, C, GCC inline ASM, basic Linux and Windows cmd usage.

Index

• x86 OS development using Bochs emulator (x86osdev)
• Index
• Install Bochs
• Usage and Debug
• Bochs Software Magic Breakpoint
• Bochs Input and Output debugger macros - BochsConsolePrintChar and BochsBreak
• Advanced Bochs debugging
• How to modify a project - optional step
  • Windows
  • Debian based
  • Compilation normal projects
  • Compilation initrd projects
  • Update floppy.img
• boot code - bochs/x86osdev/boot_code/floppy.img
  • Understanding the boot code
  • Multiboot
  • Back to the code again
  • Adding some C code
  • C code
  • More info
• Screen - bochs/x86osdev/screen/floppy.img
  • Monitor code
  • Moving the cursor
  • Scrolling the screen
  • Writing a character to the screen
  • Clearing the screen
  • Writing a string
  • Summary
  • Extensions
  • More info
• GDT and IDT - bochs/x86osdev/gdt_idt/floppy.img
  • GDT - Global Descriptor Table
  • descriptor_tables.h
  • descriptor_tables.c
  • IDT - Interrupt Descriptor Table
  • Faults, traps and exceptions
  • descriptor_tables.h
  • descriptor_tables.c
  • interrupt.s
  • isr.c
  • isr.h
  • Testing it out
  • More info
• IRQs and PIT - bochs/x86osdev/irqs_and_the_pit/floppy.img
  • IRQ - Interrupt ReQuests
  • isr.h
  • isr.c
  • PIT - Programmable Interval Timer
  • More info
• Paging - bochs/x86osdev/paging/floppy.img
  • Virtual memory
  • Paging as a concretion of virtual memory
  • Page entries
  • Page directories and tables
  • Enabling paging
  • Page faults
  • Putting it into practice
  • Simple memory management with placement malloc
  • Required definitions
  • Frame allocation
  • Paging code finally
  • page fault handler
  • Testing
  • More info
• Heap - bochs/x86osdev/heap/floppy.img
  • Data structure description
  • Allocation
  • Deallocation
  • Pseudocode
  • Implementing an ordered list
  • ordered_array.h
  • ordered_map.c
  • kheap.h
  • kheap.c
  • Expansion and contraction
  • Allocation
  • Freeing
  • paging.c
  • Testing
  • More info
• VFS and initrd - bochs/x86osdev/vfs_and_initrd/floppy.img
  • VFS - Virtual File System
  • Mountpoints
  • fs.h
  • fs.c
  • Initial Ramdisk
  • My own solution
  • Filesystem generator
  • Integrating it in to your own OS
  • initrd.h
  • initrd.c
  • Loading initrd as a multiboot module
  • Testing it out
  • More info
• Multitasking - bochs/x86osdev/multitasking/floppy.img
  • Cloning an address space
  • Cloning a directory
  • Cloning a table
  • Copying a physical frame
  • Creating a new stack
  • Actual multitasking code
  • Switching tasks
  • Testing
  • Summary
  • More info
• User Mode (and syscalls) - bochs/x86osdev/user_mode/floppy.img
  • Switching to user mode
  • task.c
  • Something to watch out for
  • System calls
  • Task State Segment
  • descriptor_tables.h
  • descriptor_tables.c
  • gdt.s
  • System call interface
  • syscall.h
  • syscall.c
  • Helper macros
  • What happens when a an interrupt occurs in user mode?
  • Testing
  • More info
• Multi core startup - bochs/x86osdev/multi_core_startup/floppy.img
  • Waking the APs
  • Initializing and differentiating the APs
  • Final notes
  • Testing
  • Interruptions in multi core
  • More info
• xv6 - bochs/x86osdev/xv6_dregmod/
  • Try it
  • Debugging with symbols
  • Compilation and modification
  • More info
• Changelog
  • New chapters
• More info

Install Bochs

For Windows all are included, just download this repo:

• https://github.com/therealdreg/x86osdev/archive/refs/heads/main.zip

For Linux you must install Bochs with debugger gui support + smp (--enable-smp, --enable-debugger and --enable-debugger-gui):

• https://bochs.sourceforge.io/doc/docbook/user/compiling.html

Usage and Debug

WARNING: wait and be patient, Bochs is slow

1. Copy bochs/x86osdev/Project/floppy.img to bochs/
2. Go to bochs/
3. run bochsdbg.bat (For Linux ./bochsdbg.sh)
4. Click Start
5. Click Continue (First Breakpoint):

6. When "Magic Breakpoint" text appears click Continue again (Second Magic Breakpoint):

IMPORTANT: When you read "Run" or "Run Bochs" it means Run bochs from bochsdbg.bat (For Linux ./bochsdbg.sh) script.

With first breakpoint its possible debug bootloader code from start.

With second magic breakpoint its possible debug kernel code from start.

Debug commands: https://bochs.sourceforge.io/doc/docbook/user/internal-debugger.html

Bochs Software Magic Breakpoint

From our OS Code:

GCC:

asm volatile ("xchgw %bx, %bx");

NASM:

xchg bx, bx

Bochs Input and Output debugger macros - BochsConsolePrintChar and BochsBreak

From our OS Code:

//outputs a character to the debug console
#define BochsConsolePrintChar(c) outportb(0xe9, c)
//stops simulation and breaks into the debug console
#define BochsBreak() outportw(0x8A00,0x8A00); outportw(0x8A00,0x08AE0);

Advanced Bochs debugging

Commands supported by port 0x8A00

• 0x8A00: Used to enable the device. Any I/O to the debug module before this command is sent is sent will simply be ignored.
• 0x8A01: Selects register 0: Memory monitoring range start address (inclusive)
• 0x8A02: Selects register 1: Memory monitoring range end address (exclusive)
• 0x8A80: Enable address range memory monitoring as indicated by register 0 and 1 and clears both registers
• 0x8AE0: Return to Debugger Prompt. If the debugger is enabled (via --enable-debugger), sending 0x8AE0 to port 0x8A00 after the device has been enabled will return the Bochs to the debugger prompt. Basically the same as doing CTRL+C.
• 0x8AE2: Instruction Trace Disable. If the debugger is enabled (via --enable-debugger), sending 0x8AE2 to port 0x8A00 after the device has been enabled will disable instruction tracing
• 0x8AE3: Instruction Trace Enable. If the debugger is enabled (via --enable-debugger), sending 0x8AE3 to port 0x8A00 after the device has been enabled will enable instruction tracing
• 0x8AE4: Register Trace Disable. If the debugger is enabled (via --enable-debugger), sending 0x8AE4 to port 0x8A00 after the device has been enabled will disable register tracing.
• 0x8AE5: Register Trace Enable. If the debugger is enabled (via --enable-debugger), sending 0x8AE5 to port 0x8A00 after the device has been enabled will enable register tracing. This currently output the value of all the registers for each instruction traced. Note: instruction tracing must