322 lines
11 KiB
Diff
322 lines
11 KiB
Diff
diff --git a/Documentation/ABI/testing/sysfs-platform-bootsplash b/Documentation/ABI/testing/sysfs-platform-bootsplash
|
|
new file mode 100644
|
|
index 000000000000..742c7b035ded
|
|
--- /dev/null
|
|
+++ b/Documentation/ABI/testing/sysfs-platform-bootsplash
|
|
@@ -0,0 +1,11 @@
|
|
+What: /sys/devices/platform/bootsplash.0/enabled
|
|
+Date: Oct 2017
|
|
+KernelVersion: 4.14
|
|
+Contact: Max Staudt <mstaudt@suse.de>
|
|
+Description:
|
|
+ Can be set and read.
|
|
+
|
|
+ 0: Splash is disabled.
|
|
+ 1: Splash is shown whenever fbcon would show a text console
|
|
+ (i.e. no graphical application is running), and a splash
|
|
+ file is loaded.
|
|
diff --git a/Documentation/bootsplash.rst b/Documentation/bootsplash.rst
|
|
new file mode 100644
|
|
index 000000000000..611f0c558925
|
|
--- /dev/null
|
|
+++ b/Documentation/bootsplash.rst
|
|
@@ -0,0 +1,285 @@
|
|
+====================
|
|
+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.
|
|
+
|
|
+
|
|
+
|
|
+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.
|
|
diff --git a/MAINTAINERS b/MAINTAINERS
|
|
index 5c237445761e..7ffac272434e 100644
|
|
--- a/MAINTAINERS
|
|
+++ b/MAINTAINERS
|
|
@@ -2709,6 +2709,8 @@ BOOTSPLASH
|
|
M: Max Staudt <mstaudt@suse.de>
|
|
L: linux-fbdev@vger.kernel.org
|
|
S: Maintained
|
|
+F: Documentation/ABI/testing/sysfs-platform-bootsplash
|
|
+F: Documentation/bootsplash.rst
|
|
F: drivers/video/fbdev/core/bootsplash*.*
|
|
F: drivers/video/fbdev/core/dummycon.c
|
|
F: include/linux/bootsplash.h
|