How To Guide How to boot with a splash screen and a progress bar

Index

Introduction

The boot splash utility, which is part of the Gentoo gensplash project, provides a background image and a progress bar during Linux kernel boot and the services loading phase.

You can choose between two boot modes: silent and verbose:

• In silent mode, a progress bar will be displayed along with the background image to inform you of the boot status.
• In verbose mode a background image will be displayed while the kernel console output will be visible on the screen. This will happen if your linux kernel will be built with the splash screen feature enabled. If it will not, verbose mode will simply display log messages as usual.

Summarizing, splash screen is a stand alone application that, with a feature enabled on kernel, also allows to interact with the system consoles.

NOTE: This little doc page will include two different splash packages. The first one is available starting from STLinux-2.0 through STLinux-2.3, as it was released. The second one, a new and more robust version, is available as STLinux-2.3 update. We will take care to distinguish through these releases in this page. To maintain compatibility with the first splashutils version and distributions, and because many informations are the same, news about STLinux-2.3 splash update are available at the end of this page, whereas the rest of it remains unmodified. It is recommended to read all the document.

If you choose to initialise your system using the initramfs (this is recommended in order to load the frame buffer as early as possible), documentation on how to do this can be found in the kernel source directory Documentation/early-userspace, and there are also useful references at the linuxdevices web page and the timesys web page.

[Top]

What you need

To allow boot splash to fully work you need to have:

• The splashutils target package correctly installed.
• A linux kernel patched with the boot splash feature. ST Linux Kernels starting from release #32 are already patched.
• The framebuffer package stgfb correctly installed (see the Framebuffer driver guide or read the <stmfb_root_dir/Linux/Documentation/*.txt> files for Rel2.3).
• Your ST board connected to the TV.

[Top]

Configuring the kernel

To use the boot splash utility you have to enable the framebuffer in your linux kernel. If you also like to display a background image for all your system consoles, you have to enable splash features in your linux kernel.

Open the kernel menuconfig and pay attention to enable (if they already aren't) the following features:

Device Drivers ---> Graphics Support ---> Support for framebuffer devices

System type ---> Big Physical Area

Device Drivers ---> Character Devices ---> Virtual Terminal

Device Drivers ---> Character Devices ---> Support for console on virtual terminal

Device Drivers ---> Graphics Support ---> Console display driver support ---> Framebuffer console support

Device Drivers ---> Graphics Support ---> Support for the framebuffer splash

--- Rel2.0 ---
Turn off Device Drivers ---> Graphics Support ---> Console display driver support ---> VGA text console

--- Rel2.2 and 2.3 ---
Device Drivers ---> Graphics Support --->Enable Software Drawing Helpers

If you like to use the initramfs as the kernel filesystem you have also to enable the following feature in the kernel configurator:

Device Drivers ---> Block devices ---> Ram disk support

You have also to specify the initial ram disk support path:

--- Rel2.0 ---

Device Drivers ---> Initial RAM disk (initrd) support

--- Rel2.2 and 2.3 ---

General setup ---> Initramfs source file(s)

[Top]

Kernel command line options

When booting the kernel, the splashutils is controlled by a number of kernel command line options. Required options are:

bigphysarea

This is required and must be at least set to bigphysarea=4000

console

console=tty1 will redirect both kernel and initscript messages to tty1

CONSOLE

CONSOLE=/dev/tty1 will redirect all initscript messages to tty1

Note: Either CONSOLE=/dev/tty1 or console=tty1 must be supplied

There are also options to control the bootsplash behaviour. The options below must all follow a splash= kernel option. As usual, splash options are separated by commas and they should form a continuous configuration string. Options are:

off

disables silent and verbose splash

verbose

start the system with a verbose splash screen

silent

start the system in the silent mode (all messages for both kernel and initscripts boot are covered by a picture)

theme:foo

use theme 'foo'

tty:n

use the n-th tty as the silent tty. Default silent tty is tty8

splash=silent,theme:st_theme CONSOLE=/dev/tty1 or
splash=silent,theme:st_theme console=tty1

[Top]

Configuring the user space

To use the boot splash application you must first load the framebuffer modules. Due to the different framebuffer implementation from Release 2.0, 2.2 and 2.3, there are three different ways to load framebuffer module. We start from a common example, working with the stb7100 board.

/sbin/insmod -f cfbfillrect.ko
/sbin/insmod -f cfbcopyarea.ko
/sbin/insmod -f cfbimgblt.ko
/sbin/insmod -f stmfb-stb7100.ko tvstandard=N bitdepth=24 fbsize=210000

/sbin/insmod -f stmfb-stb7100.ko bitdepth=24 fbsize=210000

Using the splash_util.static application you can repaint the silent background image and also update the progress bar status.

One simple solution is to add the following line inside the rcS script, at services start point:

/sbin/splash_util.static -d -t st_theme -m s -c paint -p $j

Where j is the amount of the progress bar status. In this way, whenever a service is called, the progress bar will be updated.

Example, to merge in the rcS script

...
mount -t proc proc /proc
splash=`grep -c splash /proc/cmdline`
verbose=`grep -c verbose /proc/cmdline`
max_progress=`ls /etc/rc.d/S* | wc -l`
k=`expr 65534 / $max_progress`
j=$k
for i in /etc/rc.d/S* ; do
./$i
if [ $splash -ne 0 -a $verbose -eq 0 ]; then
      /sbin/splash_util.static -d -t st_theme -m s  -c paint -p $j
      j=`expr $j + $k`
fi
done
...

In this example, all services are started inside the 'for' cycle. After each service starts (./$i), the script starts the splash_util.static application if (and only if) the kernel command line contains information about the splash application and also if it contains the word 'verbose' (...splash=verbose,...).

max_progress, k and j are useful variables to calculate the amount that the progress bar should increase (depending on the number of services).

Take care to execute this line only in 'silent' mode, otherwise the progress bar will be also displayed in 'verbose' mode. In the example above, this is obtained through the 'if' statement inside the 'for' loop.

You have to manually create the fbsplash device node (mknod /dev/fbsplash c 10 63) unless you are using the ram filesystem and the initramfs file as explained below.

Notes using the ram filesytem:

If you are using the ram filesystem, you have to add the following items in the initramfs list:

• the device /dev/fbsplash
• the binary /sbin/splash_helper
• the binary /sbin/splash_util.static
• the directory /etc/splash
• the directory /etc/splash/st_theme
• the directory /etc/splash/st_theme/images
• a symbolic link to the /etc/splash/st_theme (/etc/splash/default)
• fill the /etc/splash/st_theme directory with the .cfg file furnished by the splash util package
• fill the /etc/splash/st_theme directory with the .jpg files furnished by the splash util package
• the proc dir to allow the system to get general informations

You can find an initramfs_list example based on busybox here for Release 2.0 and here for Release 2.2. Looking these files you can simply obtain the one for Release 2.3. Using this example, you'll be able to mount a busybox filesystem.

Modify the initramfs_list PATH and SERVICE_N_# labels to complete all fields.
Take care to have installed the busybox binary before using initramfs_list.
This initramfs_list file, as explained in the documents suggested in the Introduction, will be included in the linux binary when this one will be built with the ram disk support enabled (see the Configuring the kernel section).

[Top]

What's new in splashutils for Rel2.3

As introduced above, a new splashutils package version is available as STLinux-2.3 update. This version maintains all the features as in the past and moreover add support for animations. The big news respect the previous step is the way as splashutils is used. Starting from now, user will switch from silent and verbose mode simply interacting with a FIFO, initialized by the splash daemon. This means that, although command as splash_util.static are still available, they don't allow to repaint or set nothing on screen console.
However is very important for reader to have read all the document, because some assertions (explained above) are not replied in this section.
First of all is important to say that, to fully use new splashutils, user need to upgrade his linux kernel to the #104 (or later). Starting from this kernel release a renaming step was performed (as established by the splash team). Now what that (in the kernel) was called fbsplash is renamed to fbcondecor, where fbcondecor stands for framebuffer console decoration. This to avoid misunderstanding with the user space application, just called fbsplash.
So, user who need to enable the splash feature into kernel will have to enable the following (remaining unmodified the features he will have to enable as explained in the above kernel configuring section):

Device Drivers ---> Graphics Support ---> Console display driver support ---> Support for the Framebuffer Console Decorations

fbsplashd.static -t _theme_

echo "_command_" > /lib/splash/cache/.splash