dri-devel Archive on lore.kernel.org
 help / color / Atom feed
From: Max Staudt <mstaudt@suse.de>
To: b.zolnierkie@samsung.com, linux-fbdev@vger.kernel.org
Cc: michal@markovi.net, sndirsch@suse.com, oneukum@suse.com,
	tiwai@suse.com, dri-devel@lists.freedesktop.org,
	linux-kernel@vger.kernel.org, mstaudt@suse.de,
	bernhard.rosenkranzer@linaro.org, philm@manjaro.org
Subject: [RFC PATCH v2 10/13] Documentation: Add bootsplash main documentation
Date: Wed, 13 Dec 2017 20:47:52 +0100
Message-ID: <20171213194755.3409-11-mstaudt@suse.de> (raw)
In-Reply-To: <20171213194755.3409-1-mstaudt@suse.de>

Signed-off-by: Max Staudt <mstaudt@suse.de>
---
 .../ABI/testing/sysfs-platform-bootsplash          |  11 ++
 Documentation/bootsplash.rst                       | 177 +++++++++++++++++++++
 MAINTAINERS                                        |   2 +
 3 files changed, 190 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-platform-bootsplash
 create mode 100644 Documentation/bootsplash.rst

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..8bd6805af6bf
--- /dev/null
+++ b/Documentation/bootsplash.rst
@@ -0,0 +1,177 @@
+====================
+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 initrd to load.
+  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.
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
-- 
2.12.3

_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

  parent reply index

Thread overview: 68+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-12-13 19:47 [RFC PATCH v2 00/13] Kernel based bootsplash Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 01/13] bootsplash: Initial implementation showing black screen Max Staudt
2017-12-13 23:55   ` Randy Dunlap
2017-12-14 15:37     ` Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 02/13] bootsplash: Add file reading and picture rendering Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 03/13] bootsplash: Flush framebuffer after drawing Max Staudt
2017-12-13 21:35   ` Daniel Vetter
2017-12-14 15:36     ` Max Staudt
2017-12-19 12:23       ` Daniel Vetter
2017-12-19 13:34         ` Max Staudt
2017-12-19 13:57           ` Daniel Vetter
2017-12-19 14:07             ` Oliver Neukum
2017-12-31 12:53               ` Alan Cox
2018-01-03 18:04                 ` Max Staudt
2017-12-19 15:41             ` Max Staudt
2017-12-19 16:02               ` Daniel Vetter
2017-12-19 16:23                 ` Max Staudt
2017-12-20  9:45                   ` Daniel Vetter
2017-12-19 16:09               ` Daniel Vetter
2017-12-19 16:26                 ` Max Staudt
2017-12-19 21:01               ` Ray Strode
2017-12-20 13:14                 ` Max Staudt
2017-12-20 15:35                   ` Ray Strode
2017-12-20 16:52                     ` Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 04/13] bootsplash: Add corner positioning Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 05/13] bootsplash: Add animation support Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 06/13] vt: Redraw bootsplash fully on console_unblank Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 07/13] vt: Add keyboard hook to disable bootsplash Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 08/13] sysrq: Disable bootsplash on SAK Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 09/13] fbcon: Disable bootsplash on oops Max Staudt
2017-12-13 19:47 ` Max Staudt [this message]
2017-12-13 19:47 ` [RFC PATCH v2 11/13] bootsplash: sysfs entries to load and unload files Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 12/13] tools/bootsplash: Add a basic splash file creation tool Max Staudt
2017-12-13 19:47 ` [RFC PATCH v2 13/13] tools/bootsplash: Add script and data to create sample file Max Staudt
2017-12-13 19:52 ` [RFC PATCH v2 00/13] Kernel based bootsplash Max Staudt
2017-12-19 16:16 ` Daniel Vetter
2017-12-19 17:04   ` Max Staudt
2017-12-19 17:26     ` Daniel Vetter
2017-12-19 18:40       ` Max Staudt
2017-12-20  9:43         ` Daniel Vetter
2017-12-20 10:06           ` Neil Armstrong
2017-12-20 10:14             ` Daniel Vetter
2017-12-20 14:55               ` Max Staudt
2017-12-20 15:11                 ` Daniel Vetter
2017-12-20 15:19                   ` Daniel Vetter
2017-12-20 15:22                     ` Daniel Vetter
2017-12-20 16:23                     ` Max Staudt
2017-12-20 16:15                   ` Max Staudt
2017-12-31 12:44                   ` Alan Cox
2018-01-03 18:00                     ` Max Staudt
2017-12-20 14:16             ` Max Staudt
2017-12-20 14:10           ` Max Staudt
2017-12-31 12:35         ` Alan Cox
2018-01-03 17:56           ` Max Staudt
2017-12-19 20:30     ` Ray Strode
2017-12-20 13:03       ` Max Staudt
2017-12-20 15:21         ` Ray Strode
2017-12-20 16:44           ` Max Staudt
2017-12-21 14:51             ` Ray Strode
2017-12-21 16:32               ` Max Staudt
2017-12-20 11:08   ` Johannes Thumshirn
2017-12-20 11:22     ` Daniel Stone
2017-12-20 12:48       ` Johannes Thumshirn
2017-12-29 17:13   ` Jani Nikula
2018-01-03 17:38     ` Max Staudt
2017-12-21  9:48 ` Daniel Vetter
2017-12-21 16:52   ` Max Staudt
2017-12-21 15:00 ` Philip Müller

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20171213194755.3409-11-mstaudt@suse.de \
    --to=mstaudt@suse.de \
    --cc=b.zolnierkie@samsung.com \
    --cc=bernhard.rosenkranzer@linaro.org \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=linux-fbdev@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=michal@markovi.net \
    --cc=oneukum@suse.com \
    --cc=philm@manjaro.org \
    --cc=sndirsch@suse.com \
    --cc=tiwai@suse.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

dri-devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/dri-devel/0 dri-devel/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dri-devel dri-devel/ https://lore.kernel.org/dri-devel \
		dri-devel@lists.freedesktop.org
	public-inbox-index dri-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.freedesktop.lists.dri-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git