0x646b - uart

UART in QEMU

2026-07-02T00:00:00+00:00

Motivation</h2>
In the previous post</a> we looked at how xv6 kernel startup code is implemented and verified the correctness of it by manual inspecting registers inside GDB.</p>
Today we will add print functionality to our kernel, so that we can print at various stages to verify that we are doing things correctly and also we could make use of this for `"printf debugging"</code>. Generic Virtual Platform (virt)</strong> in QEMU on which we run our OS contains one NS16550A compatible UART</strong> (universal asynchronous receiver/transmitter) device.</p>`
`We will implement the UART driver for this device in Rust and make it as similar as possible to our` `reference C source code</a>.</p>`
Note:</strong> I’m implementing just a simple driver without any lock mechanisms, meaning we cannot use the print functionality in a way that a race condition arises. For now, we will just use it in our main core (core 0) to show that UART works fine. Locks will be implemented later. As I’m writing the blog posts as I implement my Rust rewrite, there could be some updates/corrections in my latest source code on Github to what I show here.</p> </blockquote> NS16550 UART</h2> I would like to give a brief overview about NS16550 UART</strong> so that we will know how to implement the driver correctly and in an easy way. This device is the widely used and industry standard in embedded world.</p> UART acts as a bridge between processor/controller to a peripheral device. It performs:</p> Serial-to-Parallel conversion on data received from a peripheral device.</li> Parallel-to-Serial conversion on data transmitted to the peripheral device.</li> </ul> UART’s TX and RX lines should be connected to RX and TX lines of the peripheral respectively and it can receive or transmit data independently. There is no clock source to synchronize the data between these, but we do have to set same Baud rate</strong> so that the data is received/sent correctly, or else we will see garbage when we print the received data to the console.</p> This UART also contains separate 16-byte FIFOs</code> with support circuitry to minimize software overhead when handling interrupts. Along with FIFO registers we will have access to some control registers to set:</p> baud rate</li> word length</li> parity type</li> number of stop bits</li> </ul> I will explain about these things with the code snippets in the next section.</p> UART Driver</h2> We will use Polling</code> method instead of Interrupts</code> to implement our driver which makes it easier to implement just by using registers without any involvement of DMA (Direct Memory Access) or other interrupt shenanigans.</p> QEMU puts UART registers at address 0x10000000</code> -></p> memlayout.rs</strong>:</p> pub const </span>UART0</span>: </span>u64 </span>= </span>0x10000000</span>; </span></code></pre> We will use register offsets to read/write correct UART registers from this Base address using volatile pointers. The reason to use volatile read/writes instead of normal read/writes are:</p> Compiler will optimize the variables if it reasons that the variable/memory doesn’t change while it is accessed, it removes it completely.</li> But MMIO (Memory Mapped I/O) that we use for the devices can change at any point in time because it depends on the hardware not software.</li> So we will explicitly tell the compiler that we know what we are doing, please don’t optimize away MMIO accesses.</li> C reference also does the same thing here, we follow the same in Rust.</li> You could see any PAC (Peripheral Access Crate) in Rust embedded world, you will see all MMIOs are accessed this way.</li> </ul> uart.rs</strong>:</p> use crate</span>::memlayout::</span>UART0</span>; </span>use </span>core::ptr::{read_volatile, write_volatile}; </span> </span>#[</span>allow</span>(non_snake_case)] </span>fn </span>ReadReg</span>(</span>reg</span>: </span>u64</span>) -> </span>u8 </span>{ </span> </span>unsafe </span>{ </span>read_volatile</span>((</span>UART0 </span>+ reg) as </span>const u8</span>) } </span>} </span> </span>#[</span>allow</span>(non_snake_case)] </span>fn </span>WriteReg</span>(</span>reg</span>: </span>u64</span>, </span>val</span>: </span>u8</span>) { </span> </span>unsafe </span>{ </span>write_volatile</span>((</span>UART0 </span>+ reg) as </span>mut u8</span>, val) } </span>} </span></code></pre> We will now define const</code> values to store UART control registers that we use:</p> uart.rs</strong>:</p> const </span>RHR</span>: </span>u64 </span>= </span>0</span>; </span>const </span>THR</span>: </span>u64 </span>= </span>0</span>; </span> </span>const </span>DLAB_LSB</span>: </span>u64 </span>= </span>0</span>; </span>const </span>DLAB_MSB</span>: </span>u64 </span>= </span>1</span>; </span> </span>const </span>IER</span>: </span>u64 </span>= </span>1</span>; </span> </span>const </span>FCR</span>: </span>u64 </span>= </span>2</span>; </span>const </span>FCR_FIFO_ENABLE</span>: </span>u8 </span>= </span>1 </span><< </span>0</span>; </span>const </span>FCR_FIFO_CLEAR</span>: </span>u8 </span>= </span>3 </span><< </span>1</span>; </span> </span>const </span>LCR</span>: </span>u64 </span>= </span>3</span>; </span>const </span>LCR_EIGHT_BITS</span>: </span>u8 </span>= </span>3 </span><< </span>0</span>; </span>const </span>LCR_BAUD_LATCH</span>: </span>u8 </span>= </span>1 </span><< </span>7</span>; </span> </span>const </span>LSR</span>: </span>u64 </span>= </span>5</span>; </span>const </span>LSR_TX_IDLE</span>: </span>u8 </span>= </span>1 </span><< </span>5</span>; </span></code></pre> We have Receive and Transmit Holding Registers</strong> (RHR/THR) at the same offset 0</code>. Device disambiguates which one we are talking to by Direction</code>, meaning if we wrote to that address, its THR, if we read from it its RHR. We read/write data to these registers. (For now we only transmit, so RHR</code> is defined for completeness; we will use it when we add input handling.)</li> Interrupt Enable Register</strong> (IER) is present at offset 1</code> which is used to enable/disable Interrupts.</li> We have programmable baud rate functionality which can be used to set to our required baud rate by using DLAB (divisor latch access bit) and Divisor Latch registers. Here device disambiguates whether we are referring to DLAB_LSB/DLAB_MSB or RHR/THR/IER by setting or resetting LCR_BAUD_LATCH</strong> (DLAB) bit in Line Control Register</strong> (LCR) register.</li> FIFO Control Register</strong> (FCR) is used to enable FIFOs and to reset RX and TX FIFOs.</li> Line Control Register</strong> (LCR) is used for setting word length, parity, stop bits and enabling programmable baud rate.</li> Line Status Register</strong> (LSR) is used for polling RX/TX statuses to read/write RHR/THR registers.</li> </ul> UART Registers (Courtesy: TI tl16c550c Datasheet</a>)</strong></p> </blockquote> </p> Now that we have defined all the required Registers and its offsets, we could now initialize the UART</strong> in the following way for Polled mode of operation</strong> instead of Interrupt mode of operation</strong>:</p> uart.rs</strong>:</p> pub fn </span>uartinit</span>() { </span> WriteReg(</span>IER</span>, </span>0x00</span>); </span> </span> WriteReg(</span>LCR</span>, </span>LCR_BAUD_LATCH</span>); </span> WriteReg(</span>DLAB_LSB</span>, </span>0x03</span>); </span> WriteReg(</span>DLAB_MSB</span>, </span>0x00</span>); </span> </span> WriteReg(</span>LCR</span>, </span>LCR_EIGHT_BITS</span>); </span> </span> WriteReg(</span>FCR</span>, </span>FCR_FIFO_ENABLE </span>| </span>FCR_FIFO_CLEAR</span>); </span>} </span></code></pre> UART initialization is done as below:</p> First we disable interrupts as we are not using UART in Interrupt operation mode</strong>. Note that the C reference re-enables TX/RX interrupts at the end of uartinit</code>; we leave them disabled because we are purely polling, which keeps this driver simpler.</p> </li> Then we set DLAB bit so that offset 0 and 1 will refer to DLAB_LSB and DLAB_MSB respectively.</p> </li> We use 0x03</code> as our divisor to get to our desired baud rate of 38400</strong> using the following divisor formula:</p> divisor = XIN frequency input ÷ (desired baud rate x 16), where XIN frequency input is 1.8432-MHz Crystal.</p> </blockquote> </li> This baud setup has no observable effect on QEMU’s console output (QEMU still consumes the divisor, but synchronous TX doesn’t use it and the host-tty setting is a no-op for our -nographic</code> backend). We program it anyway to stay faithful to real hardware, where it’s what sets the line speed.</p> </li> We are using 8N1</code>, i.e, 8 data bits (LCR_EIGHT_BITS</code> sets the low two bits of LCR), parity disabled, 1 stop bit. As we are only touching the low 2 bits of LCR register (number of data bits), all other bits will be zero, hence we get no parity, 1 stop bit and DLAB reset back to 0.</p> </li> Then, we reset the FIFOs and enable them.</p> </li> </ul> Now that we have initialized UART, we can write a simple printf function which sends characters to THR register by polling LSR_TX_IDLE bit until it is set. This bit will say if we can send next character over a UART THR register or not.</p> uart.rs</strong>:</p> pub fn </span>uartputc_sync</span>(</span>c</span>: </span>u8</span>) { </span> </span>while </span>(ReadReg(</span>LSR</span>) & </span>LSR_TX_IDLE</span>) == </span>0 </span>{} </span> WriteReg(</span>THR</span>, c); </span>} </span></code></pre> uartputc_sync</strong> is the most important base that we use to add PRINT</strong> functionality in the kernel.</p> In C reference code, formatting of values (integers, hex, strings) is done by hand-rolled functions, but in Rust we will make use of Traits</strong> to get all of that for free from the core::fmt</code> machinery.</p> print.rs</strong>:</p> use crate</span>::uart::uartputc_sync; </span>use </span>core::fmt::{</span>self</span>, Write}; </span> </span>struct </span>UartWriter; </span> </span>impl </span>Write </span>for </span>UartWriter { </span> </span>fn </span>write_str</span>(&</span>mut </span>self</span>, </span>s</span>: &</span>str</span>) -> fmt::Result { </span> </span>for </span>&c in s.</span>as_bytes</span>() { </span> </span>uartputc_sync</span>(c); </span> } </span> Ok(()) </span> } </span>} </span> </span>pub fn </span>_print</span>(</span>args</span>: fmt::Arguments) { </span> </span>let </span>_ = UartWriter.</span>write_fmt</span>(args); </span>} </span> </span>#[</span>macro_export</span>] </span>macro_rules! </span>print { </span> ($(</span>$arg</span>:</span>tt</span>)) => {{ </span> </span>$crate</span>::print::_print(format_args!($(</span>$arg</span>))); </span> }}; </span>} </span> </span>#[</span>macro_export</span>] </span>macro_rules! </span>println { </span> () => {{ </span>$crate</span>::print::_print(format_args!("</span>\n</span>")); }}; </span> ($(</span>$arg</span>:</span>tt</span>)) => {{ </span> </span>$crate</span>::print::_print(format_args!($(</span>$arg</span>))); </span> </span>$crate</span>::print::_print(format_args!("</span>\n</span>")); </span> }}; </span>} </span></code></pre> Above is the full implementation in Rust for using print!</code> and println!</code> macros that we are familiar with in std</strong> Rust. Now even in no_std</strong> kernel, we can use the same thing. The way we achieve this is by creating a zero-sized struct called UartWriter</strong> and implement Write</strong> Trait for this struct wherein we make use of our base function uartputc_sync</strong> to send characters over UART. For printing we will make use of write_fmt</strong> function which will be implemented automatically for us because we implemented Write</strong> Trait.</p> Now, In our main</strong> function, we will make use of this macros:</p> main.rs</strong>:</p> #[</span>unsafe</span>(no_mangle)] </span>pub extern </span>"</span>C</span>" </span>fn </span>main</span>() -> ! { </span> </span>if </span>r_tp</span>() == </span>0 </span>{ </span> </span>uartinit</span>(); </span> println!("</span>xv6 kernel is booting</span>"); </span> println!("</span>Scheduler is not implemented yet !!</span>"); </span> </span>STARTED</span>.</span>store</span>(</span>true</span>, Ordering::Release); </span> } </span>else </span>{ </span> </span>while </span>!</span>STARTED</span>.</span>load</span>(Ordering::Acquire) {} </span> } </span> </span> </span>loop </span>{ </span> </span>unsafe </span>{ core::arch::asm!("</span>wfi</span>") } </span> } </span>} </span></code></pre> When we run the QEMU, it should print our 2 println lines.</p> </blockquote> Running on QEMU</h2> Similar to our previous post, we can verify our print functionality as follows:</p> Follow the below steps:</p> Checkout my repo at specified commit hash</li> </ol> ❯</span> git clone https://github.com/Karthik-d-k/xv6rs.git </span> </span>❯</span> cd xv6rs/ </span> </span>❯</span> git checkout 1dc5ebbd01ef42c9261b67d6146e1c61d528a881 </span></code></pre> Run QEMU</li> </ol> ❯</span> just qemu </span>cd</span> kernel && </span>cargo</span> build</span> --release </span> </span>Compiling</span> kernel v0.1.0 (/home/adt8kor/lws/os/xv6/xv6rs/kernel) </span>... </span> </span>Finished </span>`</span>release</span>` profile </span>[</span>optimized + debuginfo</span>]</span> target(s) </span>in</span> 0.31s </span>$</span>HOME/tools/xpack-riscv-none-elf-gcc-15.2.0-1/bin/riscv-none-elf-objdump -d</span> target/riscv64gc-unknown-none-elf/release/kernel > kernel/kernel.asm </span>$</span>HOME/tools/xpack-riscv-none-elf-gcc-15.2.0-1/bin/riscv-none-elf-objdump -t</span> target/riscv64gc-unknown-none-elf/release/kernel | </span>sed </span>'</span>1,/SYMBOL TABLE/d; s/ .* / /; /^$/d</span>' > kernel/kernel.sym </span></span> Exit QEMU with Ctrl-A X </span>qemu-system-riscv64 -machine</span> virt</span> -bios</span> none</span> -m</span> 128M</span> -nographic -smp</span> 3</span> -kernel</span> target/riscv64gc-unknown-none-elf/release/kernel </span>xv6</span> kernel is booting </span>Scheduler</span> is not implemented yet !! </span></code></pre> As you can see, QEMU successfully writes out characters to the UART THR register and we can see the same in the terminal.</p> </blockquote> Mangled UART output</h3> Our print functionality as of now only works if there’s only one writer at a time. I will show exactly how the output will be mix-matched if we were to use print macros from all the cores.</p> Note that this is a logical race on a shared hardware</strong> resource (both cores hammering the THR register), not a Rust data race / undefined behaviour. This is exactly what a lock will serialize later.</p> We shall change the main to call println! macro regardless of which core we are in, i.e, both core 1 and core 2 can write the characters at the same time.</p> #[</span>unsafe</span>(no_mangle)] </span>pub extern </span>"</span>C</span>" </span>fn </span>main</span>() -> ! { </span> </span>let</span> core_no = </span>r_tp</span>(); </span> </span> </span>if</span> core_no == </span>0 </span>{ </span> </span>uartinit</span>(); </span> println!("</span>xv6 kernel is booting on CORE </span>{}</span>", core_no); </span> println!("</span>Scheduler is not implemented yet !!</span>"); </span> </span>STARTED</span>.</span>store</span>(</span>true</span>, Ordering::Release); </span> } </span>else </span>{ </span> </span>while </span>!</span>STARTED</span>.</span>load</span>(Ordering::Acquire) {} </span> println!("</span>CORE </span>{}</span>", core_no); </span> } </span> </span> </span>loop </span>{ </span> </span>unsafe </span>{ core::arch::asm!("</span>wfi</span>") } </span> } </span>} </span></code></pre> ❯</span> just qemu </span>cd</span> kernel && </span>cargo</span> build</span> --release </span> </span>Compiling</span> kernel v0.1.0 (/home/adt8kor/lws/os/xv6/xv6rs/kernel) </span>... </span> </span>Finished </span>`</span>release</span>` profile </span>[</span>optimized + debuginfo</span>]</span> target(s) </span>in</span> 0.31s </span>$</span>HOME/tools/xpack-riscv-none-elf-gcc-15.2.0-1/bin/riscv-none-elf-objdump -d</span> target/riscv64gc-unknown-none-elf/release/kernel > kernel/kernel.asm </span>$</span>HOME/tools/xpack-riscv-none-elf-gcc-15.2.0-1/bin/riscv-none-elf-objdump -t</span> target/riscv64gc-unknown-none-elf/release/kernel | </span>sed </span>'</span>1,/SYMBOL TABLE/d; s/ .* / /; /^$/d</span>' > kernel/kernel.sym </span></span> Exit QEMU with Ctrl-A X </span>qemu-system-riscv64 -machine</span> virt</span> -bios</span> none</span> -m</span> 128M</span> -nographic -smp</span> 3</span> -kernel</span> target/riscv64gc-unknown-none-elf/release/kernel </span>xv6</span> kernel is booting on CORE 0 </span>Scheduler</span> is not implemented yet !! </span>CORE</span> CORE 21 </span></code></pre> Last line will be different/mangled every time you re-run QEMU.</p> </blockquote> Conclusion</h2> That is it for this post, I will come back with new posts when I get time to port new functionality/feature to my kernel.</p> References</h2> ByteRunner: 16550</a></li> embedded.fm: c-keyword-volatile</a></li> TI tl16c550c Datasheet</a></li> RISC-V Unprivileged Spec</a></li> RISC-V Privileged Spec</a></li> xv6 RISC-V Book</a></li> xv6 RISC-V Source code</a></li> My xv6rs repo</a></li> </ul>