Documentation/fb/fbcondecor.txt

   1 What is it?
   2 -----------
   3
   4 The framebuffer decorations are a kernel feature which allows displaying a
   5 background picture on selected consoles.
   6
   7 What do I need to get it to work?
   8 ---------------------------------
   9
  10 To get fbcondecor up-and-running you will have to:
  11  1) get a copy of splashutils [1] or a similar program
  12  2) get some fbcondecor themes
  13  3) build the kernel helper program
  14  4) build your kernel with the FB_CON_DECOR option enabled.
  15
  16 To get fbcondecor operational right after fbcon initialization is finished, you
  17 will have to include a theme and the kernel helper into your initramfs image.
  18 Please refer to splashutils documentation for instructions on how to do that.
  19
  20 [1] The splashutils package can be downloaded from:
  21     http://dev.gentoo.org/~spock/projects/splashutils/
  22
  23 The userspace helper
  24 --------------------
  25
  26 The userspace fbcondecor helper (by default: /sbin/fbcondecor_helper) is called by the
  27 kernel whenever an important event occurs and the kernel needs some kind of
  28 job to be carried out. Important events include console switches and video
  29 mode switches (the kernel requests background images and configuration
  30 parameters for the current console). The fbcondecor helper must be accessible at
  31 all times. If it's not, fbcondecor will be switched off automatically.
  32
  33 It's possible to set path to the fbcondecor helper by writing it to
  34 /proc/sys/kernel/fbcondecor.
  35
  36 *****************************************************************************
  37
  38 The information below is mostly technical stuff. There's probably no need to
  39 read it unless you plan to develop a userspace helper.
  40
  41 The fbcondecor protocol
  42 -----------------------
  43
  44 The fbcondecor protocol defines a communication interface between the kernel and
  45 the userspace fbcondecor helper.
  46
  47 The kernel side is responsible for:
  48
  49  * rendering console text, using an image as a background (instead of a
  50    standard solid color fbcon uses),
  51  * accepting commands from the user via ioctls on the fbcondecor device,
  52  * calling the userspace helper to set things up as soon as the fb subsystem
  53    is initialized.
  54
  55 The userspace helper is responsible for everything else, including parsing
  56 configuration files, decompressing the image files whenever the kernel needs
  57 it, and communicating with the kernel if necessary.
  58
  59 The fbcondecor protocol specifies how communication is done in both ways:
  60 kernel->userspace and userspace->helper.
  61
  62 Kernel -> Userspace
  63 -------------------
  64
  65 The kernel communicates with the userspace helper by calling it and specifying
  66 the task to be done in a series of arguments.
  67
  68 The arguments follow the pattern:
  69 <fbcondecor protocol version> <command> <parameters>
  70
  71 All commands defined in fbcondecor protocol v2 have the following parameters:
  72  virtual console
  73  framebuffer number
  74  theme
  75
  76 Fbcondecor protocol v1 specified an additional 'fbcondecor mode' after the
  77 framebuffer number. Fbcondecor protocol v1 is deprecated and should not be used.
  78
  79 Fbcondecor protocol v2 specifies the following commands:
  80
  81 getpic
  82 ------
  83  The kernel issues this command to request image data. It's up to the
  84  userspace  helper to find a background image appropriate for the specified
  85  theme and the current resolution. The userspace helper should respond by
  86  issuing the FBIOCONDECOR_SETPIC ioctl.
  87
  88 init
  89 ----
  90  The kernel issues this command after the fbcondecor device is created and
  91  the fbcondecor interface is initialized. Upon receiving 'init', the userspace
  92  helper should parse the kernel command line (/proc/cmdline) or otherwise
  93  decide whether fbcondecor is to be activated.
  94
  95  To activate fbcondecor on the first console the helper should issue the
  96  FBIOCONDECOR_SETCFG, FBIOCONDECOR_SETPIC and FBIOCONDECOR_SETSTATE commands,
  97  in the above-mentioned order.
  98
  99  When the userspace helper is called in an early phase of the boot process
 100  (right after the initialization of fbcon), no filesystems will be mounted.
 101  The helper program should mount sysfs and then create the appropriate
 102  framebuffer, fbcondecor and tty0 devices (if they don't already exist) to get
 103  current display settings and to be able to communicate with the kernel side.
 104  It should probably also mount the procfs to be able to parse the kernel
 105  command line parameters.
 106
 107  Note that the console sem is not held when the kernel calls fbcondecor_helper
 108  with the 'init' command. The fbcondecor helper should perform all ioctls with
 109  origin set to FBCON_DECOR_IO_ORIG_USER.
 110
 111 modechange
 112 ----------
 113  The kernel issues this command on a mode change. The helper's response should
 114  be similar to the response to the 'init' command. Note that this time the
 115  console sem is held and all ioctls must be performed with origin set to
 116  FBCON_DECOR_IO_ORIG_KERNEL.
 117
 118
 119 Userspace -> Kernel
 120 -------------------
 121
 122 Userspace programs can communicate with fbcondecor via ioctls on the
 123 fbcondecor device. These ioctls are to be used by both the userspace helper
 124 (called only by the kernel) and userspace configuration tools (run by the users).
 125
 126 The fbcondecor helper should set the origin field to FBCON_DECOR_IO_ORIG_KERNEL
 127 when doing the appropriate ioctls. All userspace configuration tools should
 128 use FBCON_DECOR_IO_ORIG_USER. Failure to set the appropriate value in the origin
 129 field when performing ioctls from the kernel helper will most likely result
 130 in a console deadlock.
 131
 132 FBCON_DECOR_IO_ORIG_KERNEL instructs fbcondecor not to try to acquire the console
 133 semaphore. Not surprisingly, FBCON_DECOR_IO_ORIG_USER instructs it to acquire
 134 the console sem.
 135
 136 The framebuffer console decoration provides the following ioctls (all defined in
 137 linux/fb.h):
 138
 139 FBIOCONDECOR_SETPIC
 140 description: loads a background picture for a virtual console
 141 argument: struct fbcon_decor_iowrapper*; data: struct fb_image*
 142 notes:
 143 If called for consoles other than the current foreground one, the picture data
 144 will be ignored.
 145
 146 If the current virtual console is running in a 8-bpp mode, the cmap substruct
 147 of fb_image has to be filled appropriately: start should be set to 16 (first
 148 16 colors are reserved for fbcon), len to a value <= 240 and red, green and
 149 blue should point to valid cmap data. The transp field is ingored. The fields
 150 dx, dy, bg_color, fg_color in fb_image are ignored as well.
 151
 152 FBIOCONDECOR_SETCFG
 153 description: sets the fbcondecor config for a virtual console
 154 argument: struct fbcon_decor_iowrapper*; data: struct vc_decor*
 155 notes: The structure has to be filled with valid data.
 156
 157 FBIOCONDECOR_GETCFG
 158 description: gets the fbcondecor config for a virtual console
 159 argument: struct fbcon_decor_iowrapper*; data: struct vc_decor*
 160
 161 FBIOCONDECOR_SETSTATE
 162 description: sets the fbcondecor state for a virtual console
 163 argument: struct fbcon_decor_iowrapper*; data: unsigned int*
 164           values: 0 = disabled, 1 = enabled.
 165
 166 FBIOCONDECOR_GETSTATE
 167 description: gets the fbcondecor state for a virtual console
 168 argument: struct fbcon_decor_iowrapper*; data: unsigned int*
 169           values: as in FBIOCONDECOR_SETSTATE
 170
 171 Info on used structures:
 172
 173 Definition of struct vc_decor can be found in linux/console_decor.h. It's
 174 heavily commented. Note that the 'theme' field should point to a string
 175 no longer than FBCON_DECOR_THEME_LEN. When FBIOCONDECOR_GETCFG call is
 176 performed, the theme field should point to a char buffer of length
 177 FBCON_DECOR_THEME_LEN.
 178
 179 Definition of struct fbcon_decor_iowrapper can be found in linux/fb.h.
 180 The fields in this struct have the following meaning:
 181
 182 vc:
 183 Virtual console number.
 184
 185 origin:
 186 Specifies if the ioctl is performed as a response to a kernel request. The
 187 fbcondecor helper should set this field to FBCON_DECOR_IO_ORIG_KERNEL, userspace
 188 programs should set it to FBCON_DECOR_IO_ORIG_USER. This field is necessary to
 189 avoid console semaphore deadlocks.
 190
 191 data:
 192 Pointer to a data structure appropriate for the performed ioctl. Type of
 193 the data struct is specified in the ioctls description.
 194
 195 *****************************************************************************
 196
 197 Credit
 198 ------
 199
 200 Original 'bootsplash' project & implementation by:
 201   Volker Poplawski <volker@poplawski.de>, Stefan Reinauer <stepan@suse.de>,
 202   Steffen Winterfeldt <snwint@suse.de>, Michael Schroeder <mls@suse.de>,
 203   Ken Wimer <wimer@suse.de>.
 204
 205 Fbcondecor, fbcondecor protocol design, current implementation & docs by:
 206   Michal Januszewski <spock@gentoo.org>
 207