206 lines
8.1 KiB
Plaintext
206 lines
8.1 KiB
Plaintext
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>
|
|
|