Edgar Luque - kernel

Creating an x86_64 kernel in Rust: Part 2

2025-08-30T00:00:00+00:00

Adding Serial output</h2>

QEMU provides serial output by specifying it in the cli options:</p>

-device</span> isa-debug-exit,iobase=0xf4,iosize=0x04 </span>\
</span>-serial</span> stdio </span>\
</span></code></pre>
The device isa-debug-exit allows us to exit QEMU easily.</p>
The serial output is a 16550 UART</a> universal asynchronous receiver-transmitter.</p>
For this, we will use the uart_16550</a> crate, which interfaces with the port-mapped I/O (basically reading/writing to specific I/O port addresses to communicate with hardware).</p>
First, let's add the dependency to our Cargo.toml</code>:</p>
[</span>dependencies</span>]
</span>uart_16550 </span>= </span>"0.3.1"
</span></code></pre>
Let's create a file named serial.rs</code>, where we will add a serial_println macro, so we can have nice debug output.</p>
use </span>core</span>::</span>fmt</span>::</span>{</span>self</span>,</span> Write}</span>;
</span>
</span>use </span>spin</span>::</span>{Once</span>, </span>mutex</span>::</span>Mutex}</span>;
</span>use </span>uart_16550</span>::</span>SerialPort</span>;
</span>
</span>static </span>SERIAL_DBG</span>: </span>Once<Mutex<SerialPort>> </span>= </span>Once</span>::</span>new()</span>;
</span>
</span>pub fn </span>init</span>() {
</span>    </span>SERIAL_DBG</span>.</span>call_once</span>(|| {
</span>        </span>let mut</span> port </span>= </span>unsafe </span>{ uart_16550</span>::</span>SerialPort</span>::</span>new(</span>0x3F8</span>) }</span>;
</span>        port</span>.</span>init</span>()</span>;
</span>        Mutex</span>::</span>new(port)
</span>    })</span>;
</span>}
</span>
</span>#</span>[</span>macro_export</span>]
</span>macro_rules! </span>serial_print </span>{
</span>    (</span>$</span>(</span>$arg</span>:</span>tt</span>)</span>*</span>) </span>=> </span>($crate</span>::</span>serial</span>::</span>_serial_print(</span>format_args!</span>(</span>$</span>($arg)</span>*</span>)))</span>;
</span>}
</span>
</span>#</span>[</span>macro_export</span>]
</span>macro_rules! </span>serial_println </span>{
</span>    () </span>=> </span>($crate</span>::</span>serial_print</span>!</span>(</span>"</span>\n</span>"</span>))</span>;
</span>    (</span>$</span>(</span>$arg</span>:</span>tt</span>)</span>*</span>) </span>=> </span>($crate</span>::</span>serial_print</span>!</span>(</span>"{}</span>\n</span>"</span>, </span>format_args!</span>(</span>$</span>($arg)</span>*</span>)))</span>;
</span>}
</span>
</span>#</span>[</span>doc</span>(hidden)]
</span>pub fn </span>_serial_print</span>(</span>args</span>: </span>fmt</span>::</span>Arguments) {
</span>    </span>unsafe </span>{
</span>        </span>// This is safe because we only call this after init() has been called,
</span>        </span>// and the UART is properly initialized
</span>        </span>SERIAL_DBG
</span>            </span>.</span>get</span>()
</span>            </span>.</span>unwrap_unchecked</span>()
</span>            </span>.</span>lock</span>()
</span>            </span>.</span>write_fmt</span>(args)
</span>            </span>.</span>unwrap</span>()</span>;
</span>    }
</span>}
</span></code></pre>
format_args!</code> doesn't heap allocate, so this works even before we have a heap allocator.</p>
The port 0x3F8</code> is the COM1 port, which is the standard first serial port address on x86 systems. QEMU maps this to the serial output we configured. You can find out more in the osdev</a> wiki.</p>
Don't forget to add the module to your main.rs:</p>
mod </span>serial</span>;
</span></code></pre>
Since we want to have serial output as early as possible (especially for debugging panics during early boot), I added the init call to the boot.rs</code> file:</p>
// boot.rs
</span>
</span>
</span>#</span>[</span>unsafe</span>(no_mangle)]
</span>unsafe extern </span>"C" </span>fn </span>kmain</span>() </span>-> </span>! </span>{
</span>    </span>// All limine requests must also be referenced in a called function, otherwise they may be
</span>    </span>// removed by the linker.
</span>    </span>assert!</span>(</span>BASE_REVISION</span>.</span>is_supported</span>())</span>;
</span>
</span>    </span>// Early init serial in case we panic on expects.
</span>    serial</span>::</span>init()</span>;
</span>
</span>    </span>/// ...
</span>}
</span></code></pre>
Since we can print now, let's modify the panic handler to print the panic info:</p>
// main.rs
</span>
</span>#</span>[</span>panic_handler</span>]
</span>fn </span>rust_panic</span>(</span>info</span>: </span>&</span>core</span>::</span>panic</span>::</span>PanicInfo) </span>-> </span>! </span>{
</span>    </span>serial_println!</span>(</span>"KERNEL PANIC:"</span>)</span>;
</span>    </span>serial_println!</span>(</span>"{info:#?}"</span>)</span>;
</span>    </span>loop </span>{
</span>        </span>hlt</span>()</span>;
</span>    }
</span>}
</span></code></pre>
Testing it out</h2>
Let's add a simple test to the main function to see the serial output working:</p>
fn </span>main</span>() </span>-> </span>! </span>{
</span>    </span>serial_println!</span>(</span>"Hello from the kernel!"</span>)</span>;
</span>    </span>serial_println!</span>(</span>"Serial output is working: {}"</span>, </span>42</span>)</span>;
</span>
</span>    </span>loop </span>{
</span>        </span>hlt</span>()</span>;
</span>    }
</span>}
</span></code></pre>
When you run make run</code>, you should see the output in your terminal since we configured QEMU with -serial stdio</code>. If everything is working correctly, you'll see your messages printed alongside any QEMU boot messages.</p>



Creating an x86_64 kernel in Rust: Part 1
2025-08-28T00:00:00+00:00
This is some kind of blog series about my journey as I learn and implement my own Rust kernel.</p>
Any knowledge shared here may not be fully true, since I do this as a hobby and I'm not an experienced kernel developer.
I'm just doing this for fun, learning about the true low level bits that make running a computer with the x86_64 architecture possible.</p>
Sometimes I will mention some names or mnemonics, and maybe I won't explain them here, but I always try to put relevant links to more information.
After all, if you want to make a kernel, you will need to do research, a lot</strong>.</p>
I also won't be doing everything from scratch, for example I will use the x86_64</code> crate for some interactions with registers, and the acpi</code> crate to parse and use the ACPI tables.</p>
The bootloader</h2>
I'll be using limine</a>, for some reasons:</p>

I like it. Feels simple and modern.</li>
It provides a really nice crate</a> with a template</a> to create a kernel.</li>
We have bootloader support with UEFI out of the box, which is what most modern systems use (instead of the older BIOS).</li>
</ul>
To start, go to the template</a> and clone it or use the template button.</p>
This template uses limine, and has a nice makefile to build and run the kernel under QEMU,
the makefile also downloads the UEFI firmware (OVMF</a>) needed by QEMU to use UEFI.</p>
I also recommend creating a .cargo</code> file inside the kernel folder with the following config.toml</code>:</p>
[</span>build</span>]
</span>target </span>= </span>"x86_64-unknown-none"
</span></code></pre>
The x86_64-unknown-none</code> is a baremetal target that fits perfectly to create a kernel.</p>
If you are using vscode I also recommend to create a settings.json</code> with the following:</p>
{
</span>    </span>"rust-analyzer.cargo.target"</span>: </span>"x86_64-unknown-none"</span>,
</span>    </span>"rust-analyzer.cargo.allTargets"</span>: </span>false
</span>}
</span></code></pre>
You should look a bit around at the makefile to understand it.</p>
I will only focus on x86_64 with UEFI, so I modified a bit the relevant runners (the one that uses cdrom and the one with hdd):</p>
.PHONY</span>: </span>run-x86_64
</span>run-x86_64</span>: </span>ovmf/ovmf-code-</span>$(</span>KARCH</span>)</span>.fd ovmf/ovmf-vars-</span>$(</span>KARCH</span>)</span>.fd </span>$(</span>IMAGE_NAME</span>)</span>.iso
</span>	</span>qemu-system-</span>$(</span>KARCH</span>) </span>\
</span>		-M</span> q35 </span>\
</span>		-drive</span> if=pflash,unit=0,format=raw,file=ovmf/ovmf-code-</span>$(</span>KARCH</span>)</span>.fd,readonly=on </span>\
</span>		-drive</span> if=pflash,unit=1,format=raw,file=ovmf/ovmf-vars-</span>$(</span>KARCH</span>)</span>.fd </span>\
</span>		-cdrom </span>$(</span>IMAGE_NAME</span>)</span>.iso </span>\
</span>		-device</span> isa-debug-exit,iobase=0xf4,iosize=0x04 </span>\
</span>		-serial</span> stdio </span>\
</span>		-no-reboot </span>\
</span>		</span>$(</span>QEMUFLAGS</span>)
</span>
</span>.PHONY</span>: </span>run-hdd-x86_64
</span>run-hdd-x86_64</span>: </span>ovmf/ovmf-code-</span>$(</span>KARCH</span>)</span>.fd ovmf/ovmf-vars-</span>$(</span>KARCH</span>)</span>.fd </span>$(</span>IMAGE_NAME</span>)</span>.hdd
</span>	</span>qemu-system-</span>$(</span>KARCH</span>) </span>\
</span>		-M</span> q35 </span>\
</span>		-drive</span> if=pflash,unit=0,format=raw,file=ovmf/ovmf-code-</span>$(</span>KARCH</span>)</span>.fd,readonly=on </span>\
</span>		-drive</span> if=pflash,unit=1,format=raw,file=ovmf/ovmf-vars-</span>$(</span>KARCH</span>)</span>.fd </span>\
</span>		-hda </span>$(</span>IMAGE_NAME</span>)</span>.hdd </span>\
</span>		-device</span> isa-debug-exit,iobase=0xf4,iosize=0x04 </span>\
</span>		-serial</span> stdio </span>\
</span>		-no-reboot </span>\
</span>		</span>$(</span>QEMUFLAGS</span>)
</span></code></pre>
The main changes are adding a serial for debug output, and disabling automatic reboot.</p>
Disabling reboot is handy in case the kernel triple faults</a>.</p>
Limine</h2>
With limine, you make "requests" to the bootloader to provide you with some information, for example to get the framebuffer, you request for it with:</p>
#</span>[</span>used</span>]
</span>#</span>[</span>unsafe</span>(link_section </span>= </span>".requests"</span>)]
</span>pub static </span>FRAMEBUFFER_REQUEST</span>:</span> FramebufferRequest </span>= </span>FramebufferRequest</span>::</span>new()</span>;
</span></code></pre>
This works alongside the support of a custom linker script, which comes with the template.</p>
The linker script is needed because we need to tell the linker exactly where to put our requests in memory so that limine can find them. Without it, the linker might put our data anywhere, and limine wouldn't know where to look:</p>
.data : {
</span>    *(.data .data.*)
</span>
</span>    /* Place the sections that contain the Limine requests as part of the .data */
</span>    /* output section. */
</span>    KEEP(*(.requests_start_marker))
</span>    KEEP(*(.requests))
</span>    KEEP(*(.requests_end_marker))
</span>} :data
</span></code></pre>
You should read the linker script and understand it.</p>
See wiki.osdev.org/Linker_Scripts</a> and docs/ld</a></p>
On the script, you will also see a relevant entry:</p>
/* We want to be placed in the topmost 2GiB of the address space, for optimisations */
</span>/* and because that is what the Limine spec mandates. */
</span>/* Any address in this region will do, but often 0xffffffff80000000 is chosen as */
</span>/* that is the beginning of the region. */
</span>. = 0xffffffff80000000;
</span></code></pre>
This puts our kernel in the higher half virtual address range, which can only be accessed in ring 0 (the highest privilege level where the kernel runs), it also puts the kernel at the very top 2gb range.</p>
The higher half approach is pretty common for kernels because it gives us some nice benefits: it protects the kernel from user programs (they can't access these addresses), and it makes memory management easier since we can map the kernel at the same virtual address in every process.</p>
Small intro to paging</h2>
Paging's main use is to provide each process with its own "virtual address space".</p>
Virtual memory is divided into fixed-size blocks called pages, while physical memory is divided into equally sized page frames. Each page can be individually mapped to any frame, avoiding memory fragmentation.
This will be the job of our frame allocator alongside the memory mapper.</p>
On x86_64, paging is achieved through the Memory Management Unit (MMU) using a series of tables:</p>

4-level page tables: PML4 -> PDPT -> PD -> PT</li>
48-bit virtual addresses (using canonical addressing)</li>
4 KiB page size (typically)</li>
</ul>
The 48-bit virtual addresses need to be canonical, that is, they have to be sign extended. Also there is a gap in virtual addresses that aren't valid due to this.</p>
Each page table has 512 entries of 8 bytes each, requiring 9 bits to address each entry.</p>
When the CPU needs to translate a virtual address, it basically does this: takes the virtual address, splits it into chunks (9 bits for each level), and uses each chunk as an index to walk through the page tables until it finds the physical address. It's like following a path through multiple directories to find a file.</p>
To improve performance, x86_64 caches recent translations in the Translation Lookaside Buffer (TLB), allowing translations to skip the multi-level table walk when cached.
The TLB must be manually invalidated by the kernel when page tables change using the invlpg</code> instruction</p>
Check out specially the osdev wiki on paging to understand more.</p>
See more:</p>

os.phil-opp.com</a></li>
wiki.osdev.org/Paging</a></li>
Introduction to Virtual Memory and the x86-64 MMU</a></li>
CS 161 - Memory layout</a></li>
</ul>
Reorganizing</h2>
I moved most of the main.rs code to a boot.rs</code> file, where I'll have most limine related stuff, the real entry point, which will call the main at main.rs</code>.</p>
I did this because it's good to separate the boot logic from the actual kernel logic. The boot stuff is pretty specific to limine and getting everything set up, while main.rs should focus on the actual kernel functionality. Makes things cleaner and easier to understand.</p>
Also created a BootInfo struct alongside a global static BOOT_INFO</code> to access it easily.</p>
// boot.rs
</span>
</span>/// Sets the base revision to the latest revision supported by the crate.
</span>/// See specification for further info.
</span>/// Be sure to mark all limine requests with #[used], otherwise they may be removed by the compiler.
</span>#</span>[</span>used</span>]
</span>// The .requests section allows limine to find the requests faster and more safely.
</span>#</span>[</span>unsafe</span>(link_section </span>= </span>".requests"</span>)]
</span>pub static </span>BASE_REVISION</span>:</span> BaseRevision </span>= </span>BaseRevision</span>::</span>new()</span>;
</span>
</span>#</span>[</span>used</span>]
</span>#</span>[</span>unsafe</span>(link_section </span>= </span>".requests"</span>)]
</span>pub static </span>FRAMEBUFFER_REQUEST</span>:</span> FramebufferRequest </span>= </span>FramebufferRequest</span>::</span>new()</span>;
</span>
</span>/// Define the start and end markers for Limine requests.
</span>#</span>[</span>used</span>]
</span>#</span>[</span>unsafe</span>(link_section </span>= </span>".requests_start_marker"</span>)]
</span>static </span>_START_MARKER</span>:</span> RequestsStartMarker </span>= </span>RequestsStartMarker</span>::</span>new()</span>;
</span>#</span>[</span>used</span>]
</span>#</span>[</span>unsafe</span>(link_section </span>= </span>".requests_end_marker"</span>)]
</span>static </span>_END_MARKER</span>:</span> RequestsEndMarker </span>= </span>RequestsEndMarker</span>::</span>new()</span>;
</span>
</span>#</span>[</span>expect</span>(unused)]
</span>pub struct </span>BootInfo </span>{
</span>    </span>pub </span>framebuffer</span>: </span>Framebuffer<</span>'static</span>>,
</span>}
</span>
</span>pub static </span>BOOT_INFO</span>: </span>Once<BootInfo> </span>= </span>Once</span>::</span>new()</span>;
</span>
</span>pub fn </span>boot_info</span>() </span>-> </span>&</span>'static</span> BootInfo {
</span>    </span>unsafe </span>{ </span>BOOT_INFO</span>.</span>get</span>()</span>.</span>unwrap_unchecked</span>() }
</span>}
</span>
</span>#</span>[</span>unsafe</span>(no_mangle)]
</span>unsafe extern </span>"C" </span>fn </span>kmain</span>() </span>-> </span>! </span>{
</span>    </span>// All limine requests must also be referenced in a called function, otherwise they may be
</span>    </span>// removed by the linker.
</span>    </span>assert!</span>(</span>BASE_REVISION</span>.</span>is_supported</span>())</span>;
</span>
</span>    </span>let</span> framebuffer </span>= </span>FRAMEBUFFER_REQUEST
</span>        </span>.</span>get_response</span>()
</span>        </span>.</span>expect</span>(</span>"need a framebuffer"</span>)
</span>        </span>.</span>framebuffers</span>()
</span>        </span>.</span>next</span>()
</span>        </span>.</span>expect</span>(</span>"need a framebuffer"</span>)</span>;
</span>
</span>    </span>let</span> boot_info </span>=</span> BootInfo {
</span>        framebuffer</span>,
</span>    }</span>;
</span>
</span>    </span>BOOT_INFO</span>.</span>call_once</span>(|| boot_info)</span>;
</span>
</span>    </span>main</span>()
</span>}
</span>
</span>
</span>// main.rs
</span>
</span>use </span>x86_64</span>::</span>instructions</span>::</span>hlt</span>;
</span>
</span>mod </span>boot</span>;
</span>
</span>fn </span>main</span>() </span>-> </span>! </span>{
</span>    </span>loop </span>{
</span>        </span>hlt</span>()</span>;
</span>    }
</span>}
</span>
</span>#</span>[</span>panic_handler</span>]
</span>fn </span>rust_panic</span>(</span>info</span>: </span>&</span>core</span>::</span>panic</span>::</span>PanicInfo) </span>-> </span>! </span>{
</span>    </span>loop </span>{
</span>        </span>hlt</span>()</span>;
</span>    }
</span>}
</span>
</span></code></pre>
Once</code> comes from the spin crate (it's like a no_std OnceCell), and hlt</code> from the x86_64</code> crate.</p>
The hlt</code> instruction is better than just doing loop {}</code> because it actually puts the CPU to sleep until an interrupt happens, which saves power and doesn't waste CPU cycles.</p>
spin </span>= </span>"0.10.0"
</span>x86_64 </span>= </span>"0.15.2"
</span></code></pre>
What's next?</h2>

Setting up a frame allocator</li>
Creating a memory mapper</li>
Initializing the kernel heap</li>
Creating the GDT.</li>
Handling interrupts and exceptions</li>
Parsing the ACPI tables.</li>
</ul>

Edgar Luque - kernel

Creating an x86_64 kernel in Rust: Part 2

Creating an x86_64 kernel in Rust: Part 1

What's next?</h2> Setting up a frame allocator</li> Creating a memory mapper</li> Initializing the kernel heap</li> Creating the GDT.</li> Handling interrupts and exceptions</li> Parsing the ACPI tables.</li> </ul>

What's next?</h2>

Setting up a frame allocator</li>
Creating a memory mapper</li>
Initializing the kernel heap</li>
Creating the GDT.</li>
Handling interrupts and exceptions</li>
Parsing the ACPI tables.</li> </ul>