SchOS/docs/architecture/graphics.md

Graphics, text and the console

Four things share this area and they are deliberately separate: the kernel's own drawing surface, the compositor's display interface, the text-rendering layer, and the crash screen.

---

The two display interfaces, and why there are two

This distinction causes confusion every time somebody meets it, so it is the first thing here.

	gfx.h	display.h
What	The kernel's own drawing surface	The compositor's interface
About	Pixels and text	Frames
Operations	draw_pixel, fill_rect, putc, text_at	acquire, present, wait_vblank
Buffering	None. Direct writes to the scanout.	Double-buffered
Users	The console and PSOGM	Schcom
Must work when	Nothing else in the system does	Userspace is healthy

That last row is the reason they are not one interface. The console and the crash screen cannot depend on a back buffer being allocatable, on a driver having a working present path, or on anything that could be the thing that just broke.

gfx — the scanout

A driver that owns a linear framebuffer publishes it with gfx_attach_scanout(), and everything above draws through gfx_* calls.

This used to be kernel/dev/vga.c, and every consumer called it by that name: panic.c drew the crash screen with vga_fill_rect, the console printed with vga_putc, /dev/fb0 handed out vga_fb_phys(). None of that has anything to do with a VGA — it is bitmap drawing over a linear framebuffer, and the only VGA-specific part was where the framebuffer came from. A second display driver is now a second caller of one function rather than an edit to the crash screen.

main() names no display driver. Whichever one owns the framebuffer the loader left running says so before any bus is enumerated, because the console draws long before PCI is walked.

display — the class

struct display_ops, found with device_find_class(DEVCLASS_DISPLAY).

acquire() allocates the back buffer on first call, never at boot — it is around two megabytes at 800×600, and a machine whose compositor never starts should not pay that. A driver that cannot double-buffer returns 0, and the caller draws directly and accepts tearing rather than not drawing at all. wait_vblank is optional for the same reason.

echo d > /proc/sysrq drives the whole path and draws a test pattern.

Drivers

VBE framebuffer (gpu/vga/)	Whatever the loader set up. Always present; this is what the splash and the console are drawn on.
virtio-gpu (gpu/virtio_gpu/)	2D, written from the OASIS specification. Full path: GET_DISPLAY_INFO, RESOURCE_CREATE_2D, RESOURCE_ATTACH_BACKING, SET_SCANOUT, TRANSFER_TO_HOST_2D, RESOURCE_FLUSH.

virtio-gpu is offered the bus before the VBE driver, so on a machine with both, the device with real mode setting and an explicit flush wins the display class. vga_pci still claims the stdvga card underneath, which is what the boot splash is drawn on — so -vga std must stay on the QEMU command line even when adding -device virtio-gpu-pci, because the loader's splash goes through VBE and there is no virtio path that early.

A framebuffer at physical zero is not a framebuffer

That last sentence used to be advice. It is now enforced, because ignoring it did not produce a machine with no splash — it produced a reboot loop.

virtio-gpu has no linear aperture, so OVMF's virtio GOP implements Blt and nothing else. On a machine whose only display is one, the firmware reports a width and a height and a FrameBufferBase of zero. Two places took that at face value:

• kmain() tested if (bi.ptr && …) — with bi.ptr already run through P2V(), and P2V(0) is KERNBASE, which is not zero. The guard could not fail, and its own comment said "drawing into address zero is a worse failure than staying quiet". It now tests the physical value before translating it.
• vga_fb_init() attached the scanout regardless, one layer down.

Either one wrote four megabytes over physical 0 — the real-mode IVT, the BIOS data area, the AP trampoline at 0x7000, the early page tables — and the machine reset before it could print anything, came back to the firmware, and did it again.

Both refuse now and say so. A machine with no usable linear framebuffer gets no graphical console, which is the truth about it; the serial line still has everything.

A virtio-gpu-only machine still does not reach a shell. It no longer corrupts memory and it explains itself, but the console path assumes a framebuffer — vt_init() reports a terminal of 0 by 0 cells — and that path has never been exercised. Supported today is stdvga, with virtio-gpu optional beside it.

/dev/fb0 speaks the Linux fbdev interface: geometry through the fbdev ioctls, and mmap of the real framebuffer at its real physical address.

mmap of /dev/fb0 is also the kernel's only chance to notice that the screen no longer belongs to the text console — after that the drawing happens with no further syscalls. fb_mapped() is called there, and fbclose() puts it back.

What the second head shows

A machine with both a stdvga and a virtio-gpu has two displays, and vgpud — the out-of-kernel driver, cmd/vgpud/main.c — owns the second one. For a long time it drew a test card there: colour bands, gradients, a checkerboard, and its own pid in binary along the bottom. That was scaffolding for ../plan/hybrid.md's H2 and H3, where a screenshot had to answer did a userspace process put this here and did the driver come back.

Both of those are closed, so the test card became the Shift mark. Which was honest about ownership and useless about everything else: a second monitor showing a logo for ever is indistinguishable from a second monitor that does not work, and that is exactly what it got called.

It shows the console now.

Before vgpud there is, the kernel and the loader do it

vgpud starts several seconds into userspace. Until then the second head used to be black — through the splash, through the F8 menu, through every boot message — which from the outside is indistinguishable from a display that does not work. Three stages now cover the whole boot, and they hand over to each other without coordinating:

The loader. LocateProtocol() answers with the first GOP and offers no way to ask for the rest, so the rest are found by handle (LocateHandleBuffer, ByProtocol). Each is fed the primary's framebuffer as a Blt source, at the points where a screen is finished: the F8 menu, the resolution chooser, system information, the splash, each segment of the kernel load. Blt rather than a second framebuffer to draw into, because a virtio GOP does not have one — the same fact that made a virtio-only machine reboot-loop.

Each stage puts the other displays into the mode the F8 menu chose, rather than leaving them in whatever the firmware picked. Without that, choosing 1024×768 changed the screen it was chosen on and left the other one at 1280×800, showing the menu and then the splash as a small rectangle in the middle of a larger black one. The loader sets the mode on each mirror GOP; the kernel's virtio driver takes gfx's dimensions over GET_DISPLAY_INFO's, for the same reason vgpud does — the host window's size is a fact about QEMU, not about the machine.

The kernel. display_mirror_console() copies the console's newly-drawn rows to the display class whenever that is a different screen. Cheap because gfx remembers which rows those were: a line of boot text is one cell-row transfer, not a screen.

Two things about that were learned the hard way, and both are load-bearing:

• It runs outside the console lock, at the end of consolewrite() and cprintf() rather than per character inside them. A display driver is entitled to say something — vga_disp_acquire() announces its back buffer — and cprintf() from inside that lock is a CPU taking a lock it already holds. The panic's call chain said so plainly, which is the argument for keeping the call chain in the report.
• "Is this the console's own screen" is asked of the scanout, not of the buffer acquire() returns. vga_fb hands back a back buffer that it later copies onto the console's framebuffer, so comparing pointers answered "a different screen" about the only screen there is — and mirrored the console onto itself through two megabytes of intermediate. display_ops grew scanout_phys to answer it as a fact about the hardware.

Then vgpud, from the same console framebuffer, by the mechanism below. The handover needs no coordination in either direction: the moment vgpud claims the device the kernel's display_acquire() returns nothing, and if vgpud exits the kernel's driver takes it back and the first line of output repaints the screen.

There is one visible gap, and it is honest: while the kernel's driver resets the device during probe, QEMU shows "Display output is not active" for a fraction of a second. A device being taken over has no scanout until the new driver sets one, and the same blink happens when vgpud claims it.

A copy with a diff

The console framebuffer is mapped through /dev/fb0; the virtio backing store is already mapped, because vgpud allocated it. So the backing holds, at all times, exactly what was last sent to the device — which means it is the previous frame, and answering "what changed" needs no third buffer. Ten times a second: compare each row, skip the ones that match, copy the ones that do not, and transfer the single rectangle spanning the rows that changed.

This is why present() became present_rect(). Moving one line of text with a full-screen transfer of a 1280×800 resource is most of a megabyte of copy for a few hundred bytes of difference, and the loop runs whether or not anything is happening.

Mapping /dev/fb0 does not take the screen away from the console — the mapping is of the same physical pages the console draws into, and the kernel's fb_mapped() only arranges a redraw when the fd is closed. vgpud never closes it.

A head larger than the console centres it on the theme ground. A head smaller shows the top-left corner, which is where a terminal puts everything worth seeing. Scaling is the alternative and it is the wrong one: text resampled to a non-integer ratio is text you cannot read.

This is not the endpoint. A compositor (Gate 3) will want this head for itself, and when there is one, the mirror goes away. Until then the honest thing for a working display to show is the system running on it.

The F8 resolution is the head's resolution

vgpud used to size itself from GET_DISPLAY_INFO, which answers with the size of the host's window — a number the person running QEMU sets by dragging a corner, and which says nothing about the machine. The resolution the F8 menu offered at boot is the one that was actually chosen, and it is the console's.

A head that mirrors the console and ignores that choice shows the right pixels in the wrong mode: pick 1024×768 at the menu and the second display stayed at whatever the window was, with the console letterboxed inside it. So console_open() runs before bring_up(), and the mode comes from the console when there is one.

That ordering is the whole of it, and it is not cosmetic: the DMA allocation is sized from those numbers and fixed for the life of the process, so a mode chosen after the fact could only ever be smaller than the window that was already paid for.

/run is not a tmpfs

Found while testing the above, and older than it: schmode reported "cannot reach vgpud on /run/vgpud — it is not running" about a process that was running perfectly well, on every boot after the first.

bind() creates a node at the path, and /run is a directory on the root filesystem rather than a tmpfs. So the node outlived the process, and the boot. The next boot's vgpud claimed the device, drew, held it — and failed bind() on a name that already existed, leaving a driver nobody could talk to and an error message that named the wrong cause.

vgpud unlinks the path before binding it, which is what a Unix daemon does. The usual objection — that it lets a second instance steal a live socket — does not apply: two vgpuds cannot coexist, because the first holds the PCI claim and the second is refused the device long before it reaches bind(). The claim is the mutual exclusion; the socket node never was.

Text

include/text.h + kernel/dev/text.c.

The font was never the problem — the character-cell grid was. The console draws text by indexing font_data[256][16] and stepping the cursor eight pixels. A grid cannot do variable-width glyphs, cannot position text anywhere except on a multiple of eight, cannot anti-alias, and cannot represent a codepoint above 255. Swapping the bitmap for a nicer bitmap changes none of that.

So the text layer fixes three things:

• Glyphs have metrics — size, bearing, advance. That is variable-width text; everything else follows from it.
• It draws into a struct surface, not into the screen. A compositor draws off-screen and presents; rendering that writes straight to the VGA aperture is unusable to it.
• The font is behind struct font_ops. The bitmap font is one implementation and a rasteriser is another, arriving without any caller changing — glyphs carry 8-bit coverage, so an anti-aliased outline renderer already has somewhere to put its output.

The font is replaceable

The console draws with the TrueType face linked into the kernel image, and will use a different one if the boot volume offers it: \schos\console.ttf, or \console.ttf, on the ESP.

cp ports/JetBrains_Mono/static/JetBrainsMono-ExtraBold.ttf \
   build/esp/schos/console.ttf

Nothing ships one, because the file that would be shipped is the file already in the kernel, and two copies of a font are two things that can disagree. What this buys is that the typeface is a property of the installation rather than of the build.

The loader reads it. The kernel could open the file itself once the root filesystem is mounted, and that is the obvious design and the wrong one: the console has been drawing since the kernel's first line, so a font that arrives later changes the cell size, which changes the number of columns, which re-lays out every terminal — and blanks them. The kernel log would disappear off the screen at the moment the root filesystem mounted, which is precisely the log a machine being brought up for the first time is being read for.

So the choice is made before anything is drawn. The loader allocates the pages as EfiReservedMemoryType — not EfiLoaderData, which the E820 handoff turns into usable memory on the argument that the loader's own pages belong to the kernel the moment it runs; true of the loader, not true of this — and hands over a physical address and a length in SCHBOOT_FONT_ADDR. The kernel reads the file where it lies. There is no copy, and no need for the contiguous allocator the kernel does not have.

Every failure falls back to the built-in font and keeps going: no file, an implausible size, no memory, a short read, or a file that will not parse. The last of those says so in the log, because a font that silently did not load looks exactly like a font that did.

One glyph blitter, and a cell is a surface

gfx.c used to walk font_data and blit glyphs itself, while text.c did the same job into a struct surface for no caller but a self-test. Two implementations of the hardest small thing in a renderer — bearings, coverage, clipping — that had to agree about a cell size only one of them was told had changed. They did not agree, and every line of PSOGM drew the next character's bitmap underneath itself.

There is one now. The console hands text_draw_glyph() the cell as a surface of its own: same pixels, same stride, origin moved and bounds set to that one cell. Clipping a tall ascender to its line is then the same bounds check that clips to the edge of a screen, and there is no second idea of clipping anywhere in the tree.

The bitmap font is reached through font_builtin() like any other provider, so the early console and the real one are one code path with different metrics. gfx.c does not include font.h any more; text.c does, being the only file that reads the array.

struct surface gained a bpp for this, because gfx_draw_pixel handles 16, 24 and 32 and a renderer replacing it had to as well. Zero means 32, which is what a UEFI GOP always is and what the loader publishes unconditionally.

What is still a grid is vt.c, and that is not a leftover. A terminal is rows and columns: VT100 escapes address them, TIOCGWINSZ reports them, and every program that draws a box assumes both. The grid that was in the way was the one in the drawing layer, and it is gone.

The TrueType rasteriser

kernel/dev/ttf.c: glyf outlines, composite glyphs with their component transforms, cmap format 4, anti-aliased scanline fill, with a host harness at tools/ttftest.c. A direct-mapped glyph cache in a 64 KB pool: one reserved slot per printable ASCII character, plus 224 shared slots keyed by codepoint for everything above it.

It is the console font. The regular weight is linked into the kernel image by the consfont rule in the Makefile and opened at 16 px before vt_init(), which is why gfx_font_init() prints nothing — there is no terminal to print to yet. A failure there is not fatal; the 8x16 bitmap font is still the fallback, and gfx_font_ready() says which one is in use.

Two bugs here were the same bug. KSTACKSIZE is 4096, and both the render path and the composite-glyph path put multi-kilobyte outlines on it as locals. They corrupted whatever was below the stack, which surfaced as user processes faulting on addresses they never touched and a panic inside freevm() — never anywhere near a font. Neither showed in the host harness, which has an 8 MB stack. That is the standing hazard of a rasteriser built from one source for both: the host is most forgiving about exactly the resource the kernel is strictest about. The outlines are static now, one per recursion level, and load_simple() is split out so the leaf's 512-byte flag array is not multiplied by the recursion depth.

Component transforms are applied, not skipped. An earlier version read a composite component's offset and stepped over its scale, reasoning that a wrong transform is worse than none. The left single quote in JetBrains Mono is the comma glyph with a scale of -1 — a 180-degree rotation — and its offset only makes sense after the rotation. Dropping the scale put the mark twelve pixels into a ten-pixel cell, where it was clipped away completely, so the character read as missing from the font rather than as misplaced.

The typefaces, both licence-checked at source:

Font	Where	Licence
JetBrains Mono	terminal and TTY	SIL OFL 1.1
Roboto	desktop and compositor	Apache-2.0

JetBrains Mono declares no Reserved Font Name, which matters more than it sounds: pre-rasterising a font into bitmaps at build time is a modification, and an RFN would forbid keeping the name on the result.

The console

kernel/core/console.c. A cursor, scrolling, and an ANSI escape parser including SGR colours and the erase operations.

cons_serial_only starts set. The display is the product; the serial line is the diagnostics. A machine that boots by printing pci: 6 devices and vga: display controller 1234:1111, aperture fd000000 to the screen the user is looking at is showing them a developer's log, and that single fact is most of what makes an OS look like a hobby project. Everything still goes out the UART. console_takeover() clears the flag on the first exec().

The console uses a cell grid whose size comes from the console font's measured advance rather than a hardcoded 8x16. Porting it onto the text layer's proportional path and deleting the grid is open work.

Two things the ANSI parser got wrong until a large program nobody here wrote exercised it properly:

ESC[m with no parameters is a reset, and sgr() iterated its parameter list — which is empty in that case, so the loop body never ran and the reset was dropped. ECMA-48 says an omitted parameter takes its default and SGR's default is 0. Programs emit the bare form constantly, so every colour set became permanent; with a background colour that meant the whole console went white-on-white and stayed there, which reads as a corrupted framebuffer rather than a missing branch.

OSC sequences must be consumed even when they are ignored. ESC ] was not a state, so the payload printed as text and a hyperlinked path arrived as Disk (]8;;file:///\]8;;\). There is no window title to set here and no hyperlink to follow, but discarding the body is not optional — the alternative is printing somebody's URL into the middle of their output.

Input

Keys reach both /dev/input/eventN and the tty line discipline, which is correct for two consumers of one keyboard and completely wrong for a full-screen program — the shell behind it quietly accumulates every keystroke and runs the lot at the next Enter.

EVIOCGRAB is the fix and it is a primitive rather than a patch. Three details matter more than the feature:

• The grab is released by the close hook, not by the program. A program that grabs the keyboard and then crashes would otherwise leave the console permanently deaf, with no way to type the command that fixes it.
• Modifier state is still tracked while grabbed, or releasing the grab hands the line discipline a stuck Shift.
• /dev/input/eventN drops its backlog on open and only queues while something has it open. Without that, opening the device replayed the keystrokes of the command line that had launched the program.

PSOGM — the crash screen

kernel/core/panic.c. The Purple Screen of Guru Meditation. Built around three decisions:

It takes the whole screen. It used to dim what was there and float a panel over it, on the argument that a crash screen which wipes the display tells you the machine is gone while one that leaves your work visible tells you it stopped. That looked good and was wrong: the thing is called a Purple Screen, and half a screen of abandoned work behind the report is a distraction at the worst possible moment.

It is not frightening. No red, no capitals, no "FATAL". A calm sentence, the Shift mark — the same one the machine drew on the splash it started with — then the facts. Whoever is reading this is already having a bad time.

The mark replaced Guru, a chamfered face drawn from primitives that lived only here. Guru's argument was identity: :( is recognisably Microsoft's, and a crash screen is the screenshot most likely to leave the machine. That holds. What does not follow is that the answer is a second mark — see ../branding/README.md.

It says considerably more than it needs to. Everything cheap to collect is collected: stop code, fault address, which CPU, which process, how far into the boot, where the kernel is loaded, and a call chain — and since debugging.md's symbol table, the call chain is names: panic+0x5f, proc_sysrq_cmd+0xb3, sys_writev+0x12b. All of it goes to the serial line in the same order, which is what bootcheck reads and what you get when the crash happens before there is a framebuffer at all.

Once painted, panicked is set and consputc spins rather than writing, so nothing can scribble over the report.

It reaches every display, including the ones the kernel gave away

The report used to go to the console framebuffer and stop there. On a machine with two heads that meant one screen saying the kernel was dead and another showing a shell prompt from a few seconds earlier — the most misleading thing a screen can do.

display_panic_present() in kernel/dev/device.c walks the rest of them, and there are two cases:

The kernel still drives it. display_acquire() hands back a buffer; the report is copied in and presented. This is the ordinary path, and it does nothing at all when the display class's buffer is the console's — a machine with one screen does not get the work done twice.

A process drives it. Harder, and the one worth having. The kernel let go of the device deliberately, and the process holding it will never run again — there is no scheduling after a panic. So vgpud registers its scanout in advance (PCIIOC_PANICFB), the kernel paints the report into that memory, and the driver the device was taken from is asked to put it on screen one last time: panic_present in struct pci_driver.

For virtio-gpu that means resetting the device out from under a driver that is still nominally running — safe here and nowhere else, because nothing is going to run again — and rebuilding one queue from 20 KB of static memory. No allocation, no locks, no sleeping, and every spin bounded: a crash screen that hangs has taken away the serial log's last chance to be read.

Neither announces itself on the serial line. The report says what happened and where to read it again; which monitors it reached is not part of that, and a crash screen is not the place to narrate the crash screen.

It is no longer the only copy

This screen used to be the only artefact of a panic — this file said so, and so did panic.c's own header. That stopped being true when the kernel log started outliving the kernel, and the closing lines changed to match:

This report is in /proc/kmsg after a restart.
schdbg, or Ctrl-G on the console, asks more.
PSOGM  --  Purple Screen of Guru Meditation

The first line replaced an addr2line command, which the call chain no longer needs. It is the more useful instruction by a wide margin, and it is the one nobody would guess: restart and read it beats photographing the screen.

The QR code below is still drawn, and still earns its place — it is the only channel that works when the machine will not come back at all.

The QR code

kernel/core/qr.c. A panic report is worth nothing if it cannot leave a machine whose network stack is dead, and a phone camera is an out-of-band channel needing no driver on our side.

It encodes the report itself, not a URL — it reaches nothing. Deliberately small in three ways: byte mode only, EC level L only (the screen is a clean, evenly lit, high-contrast source; the damage QR's stronger levels protect against does not apply), and versions 1–6 only, stopping short of version 7's extra version-information blocks and version 10's wider count field.

134 bytes is a large crash report. If a payload ever needs more, the honest fix is to shorten the report.

It draws unconditionally rather than on a keypress, which is better: it costs nothing, and requiring input would mean the one case where input is least trustworthy is also the case where the report is hardest to retrieve. Verified by make crashshot && make crashqr, which decodes the symbol out of the captured framebuffer.

One palette

include/theme.h. There were three unrelated designs and the seams showed: the splash was deep purple with gold text deliberately matching the panic screen, the console was cream with near-black text, and so a healthy boot was dressed as a crash and then abruptly became an amber terminal.

The rule: normal states are calm and dark; only failure is loud.

Boot, console and shell share SCH_BG/SCH_FG — near-black with a slight blue cast rather than pure #000, because pure black on an LCD reads as "the machine is off". PSOGM keeps the full-bleed purple entirely to itself, which is what makes it mean something.

---

What it does not do

• The console still has its cell grid. Cells are now a Unicode codepoint drawn by the TrueType rasteriser rather than a CP437 byte drawn from a bitmap, and the cell size follows the font's measured advance — but it is still a fixed grid, and the text layer's proportional path is unused by it.
• No mode setting. Resolution is whatever the loader asked for. There is no /dev/dri-style device and no way to change it at runtime.
• No double buffering in practice. display_ops.acquire is specified and the compositor needs it; virtio-gpu binds but exposes no modeset API, and wait_vblank is unimplemented everywhere.
• No hardware acceleration of any kind, and none is planned before 2D blit.
• No CFF/Type 2 charstrings, so OTF fonts do not render — that is a separate font_ops provider and a bytecode interpreter, not an extension of the glyf path. TrueType hinting is deliberately out of scope.
• No text layout library. Advance widths exist per glyph; kerning, shaping and line breaking do not.
• The glyph cache has 224 slots above ASCII, direct-mapped by codepoint modulo that. One European language fits without collisions; mixing scripts costs collisions, and a full pool is emptied and refilled rather than evicted entry by entry, because a linear pool cannot reclaim one glyph's bytes.
• No composite point-matching. Components positioned by matching a point in the base rather than by an offset are placed at the origin. Fonts that use it are rare and none in the tree do.
• PSOGM renders and stops. The interactive crash mode described in ../plan/roadmap.md — walk the stack, read another process's memory, dump page tables — is designed and not built.