208 lines
7.9 KiB
Plaintext
208 lines
7.9 KiB
Plaintext
What is it?
|
|
-----------
|
|
|
|
The framebuffer splash is a kernel feature that allows displaying a background
|
|
picture on selected consoles.
|
|
|
|
What do I need to get it to work?
|
|
---------------------------------
|
|
|
|
To get fb splash up-and-running you will have to:
|
|
1) get a copy of splashutils [1] or a similar program
|
|
2) get some splash themes
|
|
3) build the kernel helper program
|
|
4) build your kernel with the FB_SPLASH option enabled.
|
|
|
|
To get fbsplash operational right after fbcon initialization is finished, you
|
|
will have to include a theme and the kernel helper into your initramfs image.
|
|
Please refer to splashutils documentation for instructions on how to do that.
|
|
|
|
[1] The splashutils package can be downloaded from:
|
|
http://dev.gentoo.org/~spock/projects/splashutils/
|
|
|
|
The userspace helper
|
|
--------------------
|
|
|
|
The userspace splash helper (by default: /sbin/splash_helper) is called by the
|
|
kernel whenever an important event occurs and the kernel needs some kind of
|
|
job to be carried out. Important events include console switches and video
|
|
mode switches (the kernel requests background images and configuration
|
|
parameters for the current console). The splash helper must be accessible at
|
|
all times. If it's not, fbsplash will be switched off automatically.
|
|
|
|
It's possible to set path to the splash helper by writing it to
|
|
/proc/sys/kernel/fbsplash.
|
|
|
|
*****************************************************************************
|
|
|
|
The information below is mostly technical stuff. There's probably no need to
|
|
read it unless you plan to develop a userspace helper.
|
|
|
|
The splash protocol
|
|
-------------------
|
|
|
|
The splash protocol defines a communication interface between the kernel and
|
|
the userspace splash helper.
|
|
|
|
The kernel side is responsible for:
|
|
|
|
* rendering console text, using an image as a background (instead of a
|
|
standard solid color fbcon uses),
|
|
* accepting commands from the user via ioctls on the fbsplash device,
|
|
* calling the userspace helper to set things up as soon as the fb subsystem
|
|
is initialized.
|
|
|
|
The userspace helper is responsible for everything else, including parsing
|
|
configuration files, decompressing the image files whenever the kernel needs
|
|
it, and communicating with the kernel if necessary.
|
|
|
|
The splash protocol specifies how communication is done in both ways:
|
|
kernel->userspace and userspace->helper.
|
|
|
|
Kernel -> Userspace
|
|
-------------------
|
|
|
|
The kernel communicates with the userspace helper by calling it and specifying
|
|
the task to be done in a series of arguments.
|
|
|
|
The arguments follow the pattern:
|
|
<splash protocol version> <command> <parameters>
|
|
|
|
All commands defined in splash protocol v2 have the following parameters:
|
|
virtual console
|
|
framebuffer number
|
|
theme
|
|
|
|
Splash protocol v1 specified an additional 'fbsplash mode' after the
|
|
framebuffer number. Splash protocol v1 is deprecated and should not be used.
|
|
|
|
Splash protocol v2 specifies the following commands:
|
|
|
|
getpic
|
|
------
|
|
The kernel issues this command to request image data. It's up to the
|
|
userspace helper to find a background image appropriate for the specified
|
|
theme and the current resolution. The userspace helper should respond by
|
|
issuing the FBIOSPLASH_SETPIC ioctl.
|
|
|
|
init
|
|
----
|
|
The kernel issues this command after the fbsplash device is created and
|
|
the fbsplash interface is initialized. Upon receiving 'init', the userspace
|
|
helper should parse the kernel command line (/proc/cmdline) or otherwise
|
|
decide whether fbsplash is to be activated.
|
|
|
|
To activate fbsplash on the first console the helper should issue the
|
|
FBIOSPLASH_SETCFG, FBIOSPLASH_SETPIC and FBIOSPLASH_SETSTATE commands,
|
|
in the above-mentioned order.
|
|
|
|
When the userspace helper is called in an early phase of the boot process
|
|
(right after the initialization of fbcon), no filesystems will be mounted.
|
|
The helper program should mount sysfs and then create the appropriate
|
|
framebuffer, fbsplash and tty0 devices (if they don't already exist) to get
|
|
current display settings and to be able to communicate with the kernel side.
|
|
It should probably also mount the procfs to be able to parse the kernel
|
|
command line parameters.
|
|
|
|
Note that the console sem is not held when the kernel calls splash_helper
|
|
with the 'init' command. The splash helper should perform all ioctls with
|
|
origin set to FB_SPLASH_IO_ORIG_USER.
|
|
|
|
modechange
|
|
----------
|
|
The kernel issues this command on a mode change. The helper's response should
|
|
be similar to the response to the 'init' command. Note that this time the
|
|
console sem is held and all ioctls must be performed with origin set to
|
|
FB_SPLASH_IO_ORIG_KERNEL.
|
|
|
|
|
|
Userspace -> Kernel
|
|
-------------------
|
|
|
|
Userspace programs can communicate with fbsplash via ioctls on the fbsplash
|
|
device. These ioctls are to be used by both the userspace helper (called
|
|
only by the kernel) and userspace configuration tools (run by the users).
|
|
|
|
The splash helper should set the origin field to FB_SPLASH_IO_ORIG_KERNEL
|
|
when doing the appropriate ioctls. All userspace configuration tools should
|
|
use FB_SPLASH_IO_ORIG_USER. Failure to set the appropriate value in the origin
|
|
field when performing ioctls from the kernel helper will most likely result
|
|
in a console deadlock.
|
|
|
|
FB_SPLASH_IO_ORIG_KERNEL instructs fbsplash not to try to acquire the console
|
|
semaphore. Not surprisingly, FB_SPLASH_IO_ORIG_USER instructs it to acquire
|
|
the console sem.
|
|
|
|
The framebuffer splash provides the following ioctls (all defined in
|
|
linux/fb.h):
|
|
|
|
FBIOSPLASH_SETPIC
|
|
description: loads a background picture for a virtual console
|
|
argument: struct fb_splash_iowrapper*; data: struct fb_image*
|
|
notes:
|
|
If called for consoles other than the current foreground one, the picture data
|
|
will be ignored.
|
|
|
|
If the current virtual console is running in a 8-bpp mode, the cmap substruct
|
|
of fb_image has to be filled appropriately: start should be set to 16 (first
|
|
16 colors are reserved for fbcon), len to a value <= 240 and red, green and
|
|
blue should point to valid cmap data. The transp field is ingored. The fields
|
|
dx, dy, bg_color, fg_color in fb_image are ignored as well.
|
|
|
|
FBIOSPLASH_SETCFG
|
|
description: sets the fbsplash config for a virtual console
|
|
argument: struct fb_splash_iowrapper*; data: struct vc_splash*
|
|
notes: The structure has to be filled with valid data.
|
|
|
|
FBIOSPLASH_GETCFG
|
|
description: gets the fbsplash config for a virtual console
|
|
argument: struct fb_splash_iowrapper*; data: struct vc_splash*
|
|
|
|
FBIOSPLASH_SETSTATE
|
|
description: sets the fbsplash state for a virtual console
|
|
argument: struct fb_splash_iowrapper*; data: unsigned int*
|
|
values: 0 = disabled, 1 = enabled.
|
|
|
|
FBIOSPLASH_GETSTATE
|
|
description: gets the fbsplash state for a virtual console
|
|
argument: struct fb_splash_iowrapper*; data: unsigned int*
|
|
values: as in FBIOSPLASH_SETSTATE
|
|
|
|
Info on used structures:
|
|
|
|
Definition of struct vc_splash can be found in linux/console_splash.h. It's
|
|
heavily commented. Note that the 'theme' field should point to a string
|
|
no longer than FB_SPLASH_THEME_LEN. When FBIOSPLASH_GETCFG call is
|
|
performed, the theme field should point to a char buffer of length
|
|
FB_SPLASH_THEME_LEN.
|
|
|
|
Definition of struct fb_splash_iowrapper can be found in linux/fb.h.
|
|
The fields in this struct have the following meaning:
|
|
|
|
vc:
|
|
Virtual console number.
|
|
|
|
origin:
|
|
Specifies if the ioctl is performed as a response to a kernel request. The
|
|
splash helper should set this field to FB_SPLASH_IO_ORIG_KERNEL, userspace
|
|
programs should set it to FB_SPLASH_IO_ORIG_USER. This field is necessary to
|
|
avoid console semaphore deadlocks.
|
|
|
|
data:
|
|
Pointer to a data structure appropriate for the performed ioctl. Type of
|
|
the data struct is specified in the ioctls description.
|
|
|
|
*****************************************************************************
|
|
|
|
Credit
|
|
------
|
|
|
|
Original 'bootsplash' project & implementation by:
|
|
Volker Poplawski <volker@poplawski.de>, Stefan Reinauer <stepan@suse.de>,
|
|
Steffen Winterfeldt <snwint@suse.de>, Michael Schroeder <mls@suse.de>,
|
|
Ken Wimer <wimer@suse.de>.
|
|
|
|
Fbsplash, splash protocol design, current implementation & docs by:
|
|
Michal Januszewski <spock@gentoo.org>
|
|
|