gfxboot reference

Abstract

Creating bootloader graphics with gfxboot for syslinux/isolinux, lilo, and grub.

Table of Contents

Overview
Utilities
syslinux Submenus
Reference
Initialisation
Callbacks
Primary words

Overview

To make a graphical boot screen you'll have to write a small script. Optionally you might want font files, graphics files and sound files.

The script is written in a Postscript-like language. You must program everything related to graphics output in it. That does include e.g. drawing the background picture and in particular handling all kind of user input.

Font files have a special format. Create them using gfxboot-font. Maximum font file size is 512kB.

If you have written a script, convert it into byte code using gfxboot-compile.

Debugging this script is rather tedious. For this, gfxboot-compile -l will give you debug information that is useful together with the dtrace command.

Utilities

Tools needed to build a boot graphics file.

  • gfxboot-compile

    Compile source into byte code. The result (together with any other files you might need) has to be put into a cpio archive. If you are using isolinux or syslinux, this is not required, as you can read files directly from the filesystem. The compiled byte code, however, always has to be put into the cpio archive.

    Example 1. 

      # compile 'foo.ps' to 'foo', writing log to foo.log
  # Note: '-O' turns on the optimizer. You'll always want to do this.
  gfxboot-compile -O -v -l foo.log -c foo.ps foo

  # put it into a cpio archive
  # we'll assume you need a picture 'foo.jpg' and are using font 'foo.fnt'
  echo -e "foo\nfoo.jpg\nfoo.fnt" | cpio -o >bootlogo

  # 'bootlogo' is ready to use, e.g.
  # as 'gfxboot bootlogo' in isolinux.cfg


  • gfxboot-font

    Build font file using the freetype rendering engine.

  • help2txt

    Convert html files into the internal online-help format.

syslinux Submenus

gfxboot allows you to have submenus with syslinux (without the menu module) by extending the syslinux config file syntax a bit.

Submenu entries have a label stating with '->FOO ' (note the space) where FOO is an arbitrary string identifying the submenu.

Menu (or submenu) entries that have an append entry '->BAR' link to submenu BAR. The maximum submenu nesting depth is 16.

As there are spaces in labels required to make this work, use the menu label statement in syslinux.

Note that this way you can still use the label statement to reach any menu item (even if it's in a submenu) directly, which keeps the config file also usable in text mode.

Example 2. 


  # normal entry
  label linux
    kernel linux
    append initrd=initrd

  # link to submenu
  label submenu
    menu label My Submenu
    append ->1

  # 1st submenu entry
  label item1
    menu label ->1 Submenu Item #1
    kernel linux
    append initrd=initrd sub=1

  # 2nd submenu entry
  label item2
    menu label ->1 Submenu Item #2
    kernel linux
    append initrd=initrd sub=2

Reference

Comments start with '%' and extend to the end of line.

To include some other source file, do: 

%% include file

Numbers are always 32 bit signed integer. Numerical and string constants are given in a C-like way (not as in Postscript).

Example 3. 

    123, -456
    0x4567
    "Hi there\n"
    '\033', '\x1b', '\u20ac'

But: chars have values in the range 0 .. 0x1fffff.

Strings are interpreted as utf8-sequences. Alternatively you can use '\uXXXX' or '\UXXXXXXXX' to include Unicode characters.

Example 4. 

     "1 Euro = 1 €\n"
     "1 Euro = 1 \u20ac\n"
     "1 Euro = 1 \xe2\x82\xac\n"

Logical operations return values of type 'bool'. They are not identical with integers. There are no pre-defined constants 'true' and 'false'. But you can define them yourself if you need them, e.g.: 

/true 0 0 eq def

Strings and arrays are effectively pointers. So duplicating them on the stack does duplicate the pointer, not the object.

In addition, there is a unspecific pointer data type. You can use it to construct arbitrary memory references.

Variable/constants/function names can consist of everything except whitespace.

Initialisation

During initialization the config file in run. It must leave either an empty stack or a boolean 'true' value at the TOS (top of stack) to indicate the boot loader that everything worked fine. Otherwise the boot loader will assume that some error occured and not continue in graphics mode.

If you want to handle input (as you probably do) you must define at least the callback function KeyEvent.

Callbacks

Communication with the boot loader is done via callback functions. You are responsible to assign useful actions to them. See config file examples for more documentation.

  • KeyEvent

    Called if a key is pressed.

  • MenuInit

    Should draw boot menu.

  • InfoBoxInit

    Show message box (e.g. error messages).

  • InfoBoxDone

    Hide message box.

  • ProgressInit

    Initialize kernel load progress bar (syslinux/isolinux only).

  • ProgressDone

    Hide progress bar.

  • ProgressUpdate

    Advance progress bar.

  • PasswordInit

    Show password dialog.

  • PasswordDone

    Hide password dialog.

  • Timeout

    Timeout counter; called every 18.3th second until timeout occurs.

  • Timer

    Called every 18.3th second regardless of timeout.

Primary words