satip-axe/kernel/Documentation/fb/splash.txt

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>