Let’s write a UART driver

The QEMU ‘virt’ machine has a PL011 UART, so let’s write a driver for that.

  1. const FLAG_REGISTER_OFFSET: usize = 0x18;
  2. const FR_BUSY: u8 = 1 << 3;
  3. const FR_TXFF: u8 = 1 << 5;
  5. /// Minimal driver for a PL011 UART.
  6. #[derive(Debug)]
  7. pub struct Uart {
  8.     base_address: *mut u8,
  9. }
  11. impl Uart {
  12.     /// Constructs a new instance of the UART driver for a PL011 device at the
  13.     /// given base address.
  14.     ///
  15.     /// # Safety
  16.     ///
  17.     /// The given base address must point to the 8 MMIO control registers of a
  18.     /// PL011 device, which must be mapped into the address space of the process
  19.     /// as device memory and not have any other aliases.
  20.     pub unsafe fn new(base_address: *mut u8) -> Self {
  21.         Self { base_address }
  22.     }
  24.     /// Writes a single byte to the UART.
  25.     pub fn write_byte(&self, byte: u8) {
  26.         // Wait until there is room in the TX buffer.
  27.         while self.read_flag_register() & FR_TXFF != 0 {}
  29.         // SAFETY: We know that the base address points to the control
  30.         // registers of a PL011 device which is appropriately mapped.
  31.         unsafe {
  32.             // Write to the TX buffer.
  33.             self.base_address.write_volatile(byte);
  34.         }
  36.         // Wait until the UART is no longer busy.
  37.         while self.read_flag_register() & FR_BUSY != 0 {}
  38.     }
  40.     fn read_flag_register(&self) -> u8 {
  41.         // SAFETY: We know that the base address points to the control
  42.         // registers of a PL011 device which is appropriately mapped.
  43.         unsafe { self.base_address.add(FLAG_REGISTER_OFFSET).read_volatile() }
  44.     }
  45. }
  • Note that Uart::new is unsafe while the other methods are safe. This is because as long as the caller of Uart::new guarantees that its safety requirements are met (i.e. that there is only ever one instance of the driver for a given UART, and nothing else aliasing its address space), then it is always safe to call write_byte later because we can assume the necessary preconditions.
  • We could have done it the other way around (making new safe but write_byte unsafe), but that would be much less convenient to use as every place that calls write_byte would need to reason about the safety
  • This is a common pattern for writing safe wrappers of unsafe code: moving the burden of proof for soundness from a large number of places to a smaller number of places.