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

What is it?
-----------

The framebuffer decorations are a kernel feature which allows displaying a
background picture on selected consoles.

What do I need to get it to work?
---------------------------------

To get fbcondecor up-and-running you will have to:
 1) get a copy of splashutils [1] or a similar program
 2) get some fbcondecor themes
 3) build the kernel helper program
 4) build your kernel with the FB_CON_DECOR option enabled.

To get fbcondecor 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 fbcondecor helper (by default: /sbin/fbcondecor_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 fbcondecor helper must be accessible at
all times. If it's not, fbcondecor will be switched off automatically.

It's possible to set path to the fbcondecor helper by writing it to
/proc/sys/kernel/fbcondecor.

*****************************************************************************

The information below is mostly technical stuff. There's probably no need to
read it unless you plan to develop a userspace helper.

The fbcondecor protocol
-----------------------

The fbcondecor protocol defines a communication interface between the kernel and
the userspace fbcondecor 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 fbcondecor 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 fbcondecor 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:
<fbcondecor protocol version> <command> <parameters>

All commands defined in fbcondecor protocol v2 have the following parameters:
 virtual console
 framebuffer number
 theme

Fbcondecor protocol v1 specified an additional 'fbcondecor mode' after the
framebuffer number. Fbcondecor protocol v1 is deprecated and should not be used.

Fbcondecor 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 FBIOCONDECOR_SETPIC ioctl.

init
----
 The kernel issues this command after the fbcondecor device is created and
 the fbcondecor interface is initialized. Upon receiving 'init', the userspace
 helper should parse the kernel command line (/proc/cmdline) or otherwise
 decide whether fbcondecor is to be activated.

 To activate fbcondecor on the first console the helper should issue the
 FBIOCONDECOR_SETCFG, FBIOCONDECOR_SETPIC and FBIOCONDECOR_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, fbcondecor 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 fbcondecor_helper
 with the 'init' command. The fbcondecor helper should perform all ioctls with
 origin set to FBCON_DECOR_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
 FBCON_DECOR_IO_ORIG_KERNEL.


Userspace -> Kernel
-------------------

Userspace programs can communicate with fbcondecor via ioctls on the
fbcondecor 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 fbcondecor helper should set the origin field to FBCON_DECOR_IO_ORIG_KERNEL+when doing the appropriate ioctls. All userspace configuration tools should
use FBCON_DECOR_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.

FBCON_DECOR_IO_ORIG_KERNEL instructs fbcondecor not to try to acquire the console
semaphore. Not surprisingly, FBCON_DECOR_IO_ORIG_USER instructs it to acquire
the console sem.

The framebuffer console decoration provides the following ioctls (all defined in
linux/fb.h):

FBIOCONDECOR_SETPIC
description: loads a background picture for a virtual console
argument: struct fbcon_decor_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.

FBIOCONDECOR_SETCFG
description: sets the fbcondecor config for a virtual console
argument: struct fbcon_decor_iowrapper*; data: struct vc_decor*
notes: The structure has to be filled with valid data.

FBIOCONDECOR_GETCFG
description: gets the fbcondecor config for a virtual console
argument: struct fbcon_decor_iowrapper*; data: struct vc_decor*

FBIOCONDECOR_SETSTATE
description: sets the fbcondecor state for a virtual console
argument: struct fbcon_decor_iowrapper*; data: unsigned int*
          values: 0 = disabled, 1 = enabled.

FBIOCONDECOR_GETSTATE
description: gets the fbcondecor state for a virtual console
argument: struct fbcon_decor_iowrapper*; data: unsigned int*
          values: as in FBIOCONDECOR_SETSTATE

Info on used structures:

Definition of struct vc_decor can be found in linux/console_decor.h. It's
heavily commented. Note that the 'theme' field should point to a string
no longer than FBCON_DECOR_THEME_LEN. When FBIOCONDECOR_GETCFG call is
performed, the theme field should point to a char buffer of length
FBCON_DECOR_THEME_LEN.

Definition of struct fbcon_decor_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
fbcondecor helper should set this field to FBCON_DECOR_IO_ORIG_KERNEL, userspace
programs should set it to FBCON_DECOR_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>.

Fbcondecor, fbcondecor protocol design, current implementation & docs by:
  Michal Januszewski <spock@gentoo.org>