PC Screen Font

From OSDev Wiki
Jump to: navigation, search

On every Linux distributions, you can find a lot of console fonts with the extension .psf or .psfu. They can be found in /usr/share/kbd/consolefonts/. This article describes how to display those on graphical screen, which has the advantage that you don't have to mess with your fonts, you can directly use the ones shipped with your Linux. The other advantage is that PSF fonts can store the whole UNICODE character set, although consolefonts have maximum 512 glyphs usually.


Structure of file

The PSF file itself consist of a header, bitmaps for the glyphs and optionally a unicode character translation table.

File Header

It's a fixed, 32 bytes long chunk at the beginning of the file. It's as simple as it gets.

#define PSF_FONT_MAGIC 0x864ab572
typedef struct {
    uint32_t magic;         /* magic bytes to identify PSF */
    uint32_t version;       /* zero */
    uint32_t headersize;    /* offset of bitmaps in file, 32 */
    uint32_t flags;         /* 0 if there's no unicode table */
    uint32_t numglyph;      /* number of glyphs */
    uint32_t bytesperglyph; /* size of each glyph */
    uint32_t height;        /* height in pixels */
    uint32_t width;         /* width in pixels */
} PSF_font;


Each glyph is a bitmap, encoded the same way as VGA Fonts. For a 8x16 font, each glyph is 16 bytes long, and every byte encodes exactly one row of the glyph.

00000000b  byte  0
00000000b  byte  1
00000000b  byte  2
00010000b  byte  3
00111000b  byte  4
01101100b  byte  5
11000110b  byte  6
11000110b  byte  7
11111110b  byte  8
11000110b  byte  9
11000110b  byte 10
11000110b  byte 11
11000110b  byte 12
00000000b  byte 13
00000000b  byte 14
00000000b  byte 15

Unicode Table

If the flags in the PSF header is 1, it indicates that the font has a unicode table for glyph mapping. Without such a table, unicode characters and glyphs are mapped identically, so first glyph is for unicode character 0, second glyph for unicode character 1 and so forth.

The table is as follows: each glyph has a variable length record. Those are very similar to lines in a text file, only here lines are ended in 0xFF character not '\n' (0x0A). The nth line describes the nth glyph's mappings. Every line contains at least one, but possibly more UTF-8 character sequences.

Dealing with PSF

Although there are lot of PSF editors out there, I've found all of them broken or hard to use. So I'd recommend two neat perl scripts instead: readpsf, writepsf. They can convert PSF into easily editable ascii text file or a bitmap image that can be opened with Gimp or Photoshop and vice versa.

Loading the font

As described in VGA Fonts, you have several options. For simplicity, we'll embed it. Here's how to convert PSF into an ELF so that you can link with your kernel:

objcopy -O elf64-x86-64 -B i386 -I binary font.psf font.o
readelf -s font.o
Symbol table '.symtab' contains 5 entries:
   Num:    Value          Size Type    Bind   Vis      Ndx Name
     0: 0000000000000000     0 NOTYPE  LOCAL  DEFAULT  UND 
     1: 0000000000000000     0 SECTION LOCAL  DEFAULT    1 
     2: 0000000000000000     0 NOTYPE  GLOBAL DEFAULT    1 _binary_font_psf_start
     3: 0000000000008020     0 NOTYPE  GLOBAL DEFAULT    1 _binary_font_psf_end
     4: 0000000000008020     0 NOTYPE  GLOBAL DEFAULT  ABS _binary_font_psf_size

As you can see the resulting object exports three symbols that can be referenced as any other variables.

Before we can use our font, first we have to decode the unicode table. That's a bit tricky to do, and you'll have to have calloc(), but the good news is it's optional. You can skip this if you're happy with the first glyph is for character 0, second glyph is for character 1, etc. scheme.

/* import our font that's in the object file we've created above */
extern char _binary_font_psf_start;
extern char _binary_font_psf_end;
uint16_t *unicode;
void psf_init()
    uint16_t glyph = 0;
    /* cast the address to PSF header struct */
    PSF_font *font = (PSF_font*)&_binary_font_psf_start;
    /* is there a unicode table? */
    if(font->flags) {
        /* get the offset of the table */
        char *s = (char *)(
          (unsigned char*)&_binary_font_psf_start +
          font->headersize +
          font->numglyph * font->bytesperglyph
        /* allocate memory for translation table */
        unicode = calloc(USHRT_MAX, 2);
        while(s>_binary_font_psf_end) {
            uint16_t uc = (uint16_t)((unsigned char *)s[0]);
            if(uc == 0xFF) {
            } else if(uc & 128) {
                /* UTF-8 to unicode */
                if((uc & 32) == 0 ) {
                    uc = ((s[0] & 0x1F)<<6)+(s[1] & 0x3F);
                } else
                if((uc & 16) == 0 ) {
                    uc = ((((s[0] & 0xF)<<6)+(s[1] & 0x3F))<<6)+(s[2] & 0x3F);
                } else
                if((uc & 8) == 0 ) {
                    uc = ((((((s[0] & 0x7)<<6)+(s[1] & 0x3F))<<6)+(s[2] & 0x3F))<<6)+(s[3] & 0x3F);
                } else
                    uc = 0;
            /* save translation */
            unicode[uc] = glyph;
    } else {
        unicode = NULL;

Displaying a character

I'll assume that you've set up linear frame buffer properly and you can plot a pixel from your kernel. This example uses 32 bit RGBA format, but can be adopted to other formats easily.

/* the linear framebuffer */
extern char *fb;
/* number of bytes in each line, it's possible it's not screen width * bytesperpixel! */
extern int scanline;
/* import our font that's in the object file we've created above */
extern char _binary_font_start;
void putchar(
    /* note that this is int, not char as it's a unicode character */
    unsigned short int c,
    /* cursor position on screen, in characters not in pixels */
    int cx, int cy,
    /* foreground and background colors, say 0xFFFFFF and 0x000000 */
    uint32_t fg, uint32_t bg)
    /* cast the address to PSF header struct */
    PSF_font *font = (PSF_font*)&_binary_font_psf_start;
    /* we need to know how many bytes encode one row */
    int bytesperline=(font->width+7)/8;
    /* unicode translation */
    if(unicode != NULL) {
        c = unicode[c];
    /* get the glyph for the character. If there's no
       glyph for a given character, we'll display the first glyph. */
    unsigned char *glyph =
     (unsigned char*)&_binary_font_psf_start +
     font->headersize +
    /* calculate the upper left corner on screen where we want to display.
       we only do this once, and adjust the offset later. This is faster. */
    int offs =
        (cy * font->height * scanline) +
        (cx * (font->width+1) * 4);
    /* finally display pixels according to the bitmap */
    int x,y, line,mask;
        /* save the starting position of the line */
        /* display a row */
            *((uint32_t*)(&fb + line)) = ((int)*glyph) & (mask) ? fg : bg;
            /* adjust to the next pixel */
            mask >>= 1;
            line += 4;
        /* adjust to the next line */
        glyph += bytesperline;
        offs  += scanline;

With this you can display strings on a linear frame buffer just like Linux does on it's ttys. Please note that this code is not optimal, it's for demonstration purposes, but it's a good start.

External Links

Personal tools