path: root/README.md

The Linux bootsplash
====================

Date: November, 2017

Author: Max Staudt <mstaudt@suse.de>


The Linux bootsplash is a graphical replacement for the '``quiet``' boot
option, typically showing a logo and a spinner animation as the system starts.

Currently, it is a part of the Framebuffer Console support, and can be found
as ``CONFIG_BOOTSPLASH`` in the kernel configuration. This means that as long as it is enabled, it hijacks fbcon's output and draws a splash screen instead.

Purely compiling in the bootsplash will not render it functional - to actually
render a splash, you will also need a splash theme file. See the example
utility and script in ``tools/bootsplash`` for a live demo.



Motivation
==========

- The '``quiet``' boot option only suppresses most messages during boot, but
  errors are still shown.

- A user space implementation can only show a logo once user space has been
  initialized far enough to allow this. A kernel splash can display a splash
  immediately as soon as fbcon can be displayed.

- Implementing a splash screen in user space (e.g. Plymouth) is problematic
  due to resource conflicts.

  For example, if Plymouth is keeping ``/dev/fb0`` (provided via vesafb/efifb)
  open, then most DRM drivers can't replace it because the address space is
  still busy - thus leading to a VRAM reservation error.

  See: https://bugzilla.opensuse.org/show_bug.cgi?id=980750



Command line arguments
======================

``bootsplash.bootfile``
  Which file in the initramfs to load.

  The splash theme is loaded via request_firmware(), thus to load
  ``/lib/firmware/bootsplash/mytheme`` pass the command line:

  ``bootsplash.bootfile=bootsplash/mytheme``

  Note: The splash file *has to be* in the initramfs, as it needs to be
  available when the splash is initialized early on.

  Default: none, i.e. a non-functional splash, falling back to showing text.



sysfs run-time configuration
============================

``/sys/devices/platform/bootsplash.0/enabled``
  Enable/disable the bootsplash.
  The system boots with this set to 1, but will not show a splash unless
  a splash theme file is also loaded.


``/sys/devices/platform/bootsplash.0/drop_splash``
  Unload splash data and free memory.

``/sys/devices/platform/bootsplash.0/load_file``
  Load a splash file from ``/lib/firmware/``.
  Note that trailing newlines will be interpreted as part of the file name.



Kconfig
=======

``BOOTSPLASH``
  Whether to compile in bootsplash support
  (depends on fbcon compiled in, i.e. ``FRAMEBUFFER_CONSOLE=y``)



Bootsplash file format
======================

A file specified in the kernel configuration as ``CONFIG_BOOTSPLASH_FILE``
or specified on the command line as ``bootsplash.bootfile`` will be loaded
and displayed as soon as fbcon is initialized.


Main blocks
-----------

There are 3 main blocks in each file:

  - one File header
  -   n Picture headers
  -   m (Blob header + payload) blocks


Structures
----------

The on-disk structures are defined in
``drivers/video/fbdev/core/bootsplash_file.h`` and represent these blocks:

  - ``struct splash_file_header``

    Represents the file header, with splash-wide information including:

      - The magic string "``Linux bootsplash``" on big-endian platforms
        (the reverse on little endian)
      - The file format version (for incompatible updates, hopefully never)
      - The background color
      - Number of picture and blob blocks
      - Animation speed (we only allow one delay for all animations)

    The file header is followed by the first picture header.


  - ``struct splash_picture_header``

    Represents an object (picture) drawn on screen, including its immutable
    properties:
      - Width, height
      - Positioning relative to screen corners or in the center
      - Animation, if any
      - Animation type
      - Number of blobs

    The picture header is followed by another picture header, up until n
    picture headers (as defined in the file header) have been read. Then,
    the (blob header, payload) pairs follow.


  - ``struct splash_blob_header``
    (followed by payload)

    Represents one raw data stream. So far, only picture data is defined.

    The blob header is followed by a payload, then padding to n*16 bytes,
    then (if further blobs are defined in the file header) a further blob
    header.


Alignment
---------

The bootsplash file is designed to be loaded into memory as-is.

All structures are a multiple of 16 bytes long, all elements therein are
aligned to multiples of their length, and the payloads are always padded
up to multiples of 16 bytes. This is to allow aligned accesses in all
cases while still simply mapping the structures over an in-memory copy of
the bootsplash file.


Further information
-------------------

Please see ``drivers/video/fbdev/core/bootsplash_file.h`` for further
details and possible values in the file.



Hooks - how the bootsplash is integrated
========================================

``drivers/video/fbdev/core/fbcon.c``
  ``fbcon_init()`` calls ``bootsplash_init()``, which loads the default
  bootsplash file or the one specified on the kernel command line.

  ``fbcon_switch()`` draws the bootsplash when it's active, and is also
  one of the callers of ``set_blitting_type()``.

  ``set_blitting_type()`` calls ``fbcon_set_dummyops()`` when the
  bootsplash is active, overriding the text rendering functions.

  ``fbcon_cursor()`` will call ``bootsplash_disable()`` when an oops is
  being printed in order to make a kernel panic visible.

``drivers/video/fbdev/core/dummyblit.c``
  This contains the dummy text rendering functions used to suppress text
  output while the bootsplash is shown.

``drivers/tty/vt/keyboard.c``
  ``kbd_keycode()`` can call ``bootsplash_disable()`` when the user
  presses ESC or F1-F12 (changing VT). This is to provide a built-in way
  of disabling the splash manually at any time.



FAQ: Frequently Asked Questions
===============================

I want to see the log! How do I show the log?
---------------------------------------------

Press ESC while the splash is shown, or remove the ``bootsplash.bootfile``
parameter from the kernel cmdline. Without that parameter, the bootsplash
will boot disabled.


Why use FB instead of modern DRM/KMS?
-------------------------------------

This is a semantic problem:
 - What memory to draw the splash to?
 - And what mode will the screen be set to?

Using the fbdev emulation solves these issues.

Let's start from a bare KMS system, without fbcon, and without fbdev
emulation. In this case, as long as userspace doesn't open the KMS
device, the state of the screen is undefined. No framebuffer is
allocated in video RAM, and no particular mode is set.

In this case, we'd have to allocate a framebuffer to show the splash,
and set our mode ourselves. This either wastes a screenful of video RAM
if the splash is to co-exist with the userspace program's own allocated
framebuffer, or there is a flicker as we deactivate and delete the
bootsplash's framebuffer and hand control over to userspace. Since we
may set a different mode than userspace, we'd also have flicker due
to mode switching.

This logic is already contained in every KMS driver that performs fbdev
emulation. So we might as well use that. And the correct API to do so is
fbdev. Plus, we get compatibility with old, pure fbdev drivers for free.
With the fbdev emulation, there is *always* a well-defined framebuffer
to draw on. And the selection of mode has already been done by the
graphics driver, so we don't need to reinvent that wheel, either.
Finally, if userspace decides to use /dev/fbX, we don't have to worry
about wasting video RAM, either.


Why is the bootsplash integrated in fbcon?
------------------------------------------

Right now, the bootsplash is drawn from within fbcon, as this allows us
to easily know *when* to draw - i.e. when we're safe from fbcon and
userspace drawing all over our beautiful splash logo.

Separating them is not easy - see the to-do list below.



TO DO list for future development
=================================

Second enable/disable switch for the system
-------------------------------------------

It may be helpful to differentiate between the system and the user
switching off the bootsplash. Thus, the system may make it disappear and
reappear e.g. for a password prompt, yet once the user has pressed ESC,
it could stay gone.


Fix buggy DRM/KMS drivers
-------------------------

Currently, the splash code manually checks for fbdev emulation provided by
the ast, cirrus, and mgag200 DRM/KMS drivers.
These drivers use a manual mechanism similar to deferred I/O for their FB
emulation, and thus need to be manually flushed onto the screen in the same
way.

This may be improved upon in several ways:

1. Changing these drivers to expose the fbdev BO's memory directly, like
   bochsdrmfb does.
2. Creating a new fb_ops->fb_flush() API to allow the kernel to flush the
   framebuffer once the bootsplash has been drawn into it.


Separating from fbcon
---------------------

Separating these two components would yield independence from fbcon being
compiled into the kernel, and thus lowering code size in embedded
applications.

To do this cleanly will involve a clean separation of users of an FB device
within the kernel, i.e. fbcon, bootsplash, and userspace. Right now, the
legacy fbcon code and VT code co-operate to switch between fbcon and
userspace (by setting the VT into KD_GRAPHICS mode). Installing a muxer
between these components ensues refactoring of old code and checking for
correct locking.