3 – Text on the screen
Goal: println! that writes to the screen – with our own font renderer, character by character, pixel by pixel.
You end up with:

Code: course/03-console/ (chapter 2
plus font.rs, console.rs, the font file and the spin crate)
What changed: diff -ru course/02-tests course/03-console (in the repository) shows every line this chapter adds.
Background: a framebuffer
Old PCs had a text mode: write a character code to address 0xB8000 and the graphics card draws it. UEFI
machines no longer have it. What every machine has is a framebuffer – a region of memory in which every pixel
of the screen is a few bytes. Write 0x00FF0000 into the right place and that pixel turns red. Everything else –
letters, lines, windows – is software.
Limine sets a graphics mode for us and tells us where the framebuffer is, if we ask:
#![allow(unused)] fn main() { /// A framebuffer: memory whose bytes are the pixels on the screen. Limine sets up a graphics mode for us. #[used] #[unsafe(link_section = ".limine_requests")] static FRAMEBUFFER: FramebufferRequest = FramebufferRequest::new(); }
The answer has five numbers we need: the address, width and height in pixels, bpp (bits per pixel;
we only handle 32: one u32 per pixel, 0x00RRGGBB) and the pitch – the number of bytes from one row of
pixels to the next. The pitch can be larger than width × 4; graphics hardware likes rows aligned to round
numbers. Forgetting the pitch gives a slanted, garbled picture.
Step 1: a font – PSF2
To draw a letter we need its shape. We use the console font of Linux, Terminus 8×16, in the PSF2 format: every
glyph is 16 bytes, one byte per pixel row, the highest bit is the leftmost pixel. An A looks like this
(# = bit set):
........
...##...
..#..#..
.#....#.
.#....#.
.######.
.#....#.
.#....#.
(the real glyph is 16 rows; this is a sketch). The file is built into the kernel – there is no file system yet:
#![allow(unused)] fn main() { /// The font built into the kernel: Terminus 8x16 (SIL Open Font License, see assets/README.md). pub static TERMINUS: &[u8] = include_bytes!("../assets/terminus-8x16.psf"); }
Font::parse checks the magic number 0x864ab572, reads the glyph size from the header and builds a table from
characters to glyph numbers. The table is needed because glyph 65 is not necessarily A: after the glyphs, the
file lists for each glyph which Unicode characters it shows (read_unicode_table). We keep characters below 256 –
enough for English and German. Everything else is drawn as ?:
#![allow(unused)] fn main() { /// The pixel rows of the glyph for `c` (one byte per row); characters the font lacks become '?'. pub fn glyph(&self, c: char) -> &[u8] { let index = self.index_of(c).or_else(|| self.index_of('?')).unwrap_or(0); let start = self.glyph_offset + index * self.height; &self.data[start..start + self.height] } }
Step 2: drawing a character
The console divides the screen into cells of 8×16 pixels – on QEMU's 1280×800 screen that is 160 × 50 characters. Drawing a character means: for every row of its glyph, for every bit, one pixel:
#![allow(unused)] fn main() { /// Draws the glyph of `c` into the cell at `column`, `row`: every font bit becomes one pixel. fn draw(&mut self, c: char, column: usize, row: usize) { let (x0, y0) = (column * self.font.width, row * self.font.height); for (dy, bits) in self.font.glyph(c).iter().enumerate() { let line = (y0 + dy) * self.stride + x0; for dx in 0..self.font.width { let on = bits & (0x80 >> dx) != 0; // the highest bit is the leftmost pixel self.pixels[line + dx] = if on { FOREGROUND } else { BACKGROUND }; } } } }
stride is the pitch in pixels (pitch / 4). Note that the console does not draw to "the screen" but into
pixels: &mut [u32] – any piece of memory. That is what makes it testable (step 5).
Step 3: lines, wrapping, scrolling
put_char keeps a cursor (column, row). \n moves to the next line; a full line wraps; and when the cursor
falls off the bottom, everything moves up by one text row:
#![allow(unused)] fn main() { /// Moves every text row up by one (copying pixels) and clears the bottom one. fn scroll(&mut self) { let row_pixels = self.font.height * self.stride; // one row of text, in pixels let used = self.rows * row_pixels; self.pixels.copy_within(row_pixels..used, 0); self.pixels[used - row_pixels..used].fill(BACKGROUND); } }
That is a copy of almost 4 MB per scrolled line – slow, but simple and correct. (The reference kernel keeps the characters in a grid as well and redraws from it; that is an optimisation for later.)
Step 4: a global console and println!
Code everywhere in the kernel should be able to print, so the console is a global. A global that changes needs
protection against two users at once; with only one CPU and no interrupts yet that cannot happen, but Rust does not
know that and insists – rightly: interrupts come in a later chapter, and then a second user can appear any time. We use a spin lock from the spin crate:
#![allow(unused)] fn main() { /// The console on the screen - `None` until `init` found a framebuffer. pub static CONSOLE: Mutex<Option<Console<'static>>> = Mutex::new(None); }
init turns Limine's answer into a Console – the one unsafe step, creating a slice from the framebuffer
address, is where we promise Rust that this memory really is ours. print! and println! write to the console
and the serial port, so the tests from chapter 2 still see everything.
In main.rs, mod console; and mod font; join the module list, spin = "0.12.3" joins the dependencies in
Cargo.toml, and kmain sets up the console once the base revision is checked – from then on println! works:
#![allow(unused)] fn main() { console::init(); println!("Hello from YAK!"); match console::CONSOLE.lock().as_ref() { Some(c) => serial_println!("Console: {} x {} characters", c.size().0, c.size().1), None => serial_println!("No 32-bit framebuffer - text goes to the serial port only"), } }
The test kmain calls console::init() too, after serial::init(): the test on the real framebuffer needs it.
Step 5: testing a picture
How do you test drawing without looking at a screen? Draw into a tiny screen in memory – 10 × 3 characters, with a stride of 88 pixels for an 80-pixel-wide picture, so that a pitch mistake shows up – and check the pixels:
#![allow(unused)] fn main() { #[test_case] fn a_full_screen_scrolls_up() { let mut pixels = [0u32; STRIDE * H]; let mut c = console(&mut pixels); write!(c, "a\nb\nc\nd").unwrap(); // 4 lines on a 3-row screen: "a" scrolls away assert!(shows(&pixels, 0, 0, 'b') && shows(&pixels, 0, 1, 'c') && shows(&pixels, 0, 2, 'd')); } }
shows compares a cell with the font's glyph, pixel by pixel. Together with tests for placement, wrapping, the
padding right of the picture and the font parser, make test now runs 12 tests. One of them works on the real
framebuffer: the console must cover the whole screen Limine gave us.
Run it
cd course/03-console
make run
The QEMU window shows the two lines from the picture above; the terminal shows them too (serial port), plus the console size:
Hello from YAK!
Console: 160 x 50 characters
Grüße - umlauts work too: äöü ÄÖÜ ß
What can go wrong
- Slanted or torn text: the pitch was ignored (
widthused instead ofstride). The test with the 88-pixel stride catches exactly this. - Some characters show up as
?: they are not in our Latin-1 table – for example–(U+2013, a dash) or€. That is the fallback working, not a bug. - Nothing on the screen, but the serial port works: Limine gave no 32-bit framebuffer (
bpp != 32), andinitleftCONSOLEatNone. - The kernel hangs in
println!: a spin lock taken twice – for example a panic while the console is locked, if the panic handler prints to the console. Our panic handler only uses the serial port, and ourSerialhas no lock (it has no state to protect). (The reference kernel's panic handler usestry_lockfor the console – seepanic_reportinkernel/src/lib.rs.)
Experiments
- Swap
FOREGROUNDandBACKGROUND. Then try0x00FF0000– which colour, and why is the byte orderRRGGBB? - Print 60 lines in a loop and watch it scroll. How long does it take (count with the serial output)?
- Draw every pixel of a glyph twice as wide and twice as high (a 16×32 console). What has to change?