From patchwork Wed Jan 17 20:54:32 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: 'Max Staudt X-Patchwork-Id: 10171589 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 58F2B603ED for ; Wed, 17 Jan 2018 20:58:13 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4B36C22638 for ; Wed, 17 Jan 2018 20:58:13 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 3F7D022A6B; Wed, 17 Jan 2018 20:58:13 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=unavailable version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 7DE0C22638 for ; Wed, 17 Jan 2018 20:58:12 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752855AbeAQU5m (ORCPT ); Wed, 17 Jan 2018 15:57:42 -0500 Received: from mx2.suse.de ([195.135.220.15]:34468 "EHLO mx2.suse.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932300AbeAQU4L (ORCPT ); Wed, 17 Jan 2018 15:56:11 -0500 X-Virus-Scanned: by amavisd-new at test-mx.suse.de Received: from relay1.suse.de (charybdis-ext.suse.de [195.135.220.254]) by mx2.suse.de (Postfix) with ESMTP id B0FCEAF7C; Wed, 17 Jan 2018 20:56:06 +0000 (UTC) From: Max Staudt To: b.zolnierkie@samsung.com, linux-fbdev@vger.kernel.org Cc: mstaudt@suse.de, dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org, tiwai@suse.com, oneukum@suse.com, msrb@suse.com, sndirsch@suse.com, michal@markovi.net, philm@manjaro.org, bernhard.rosenkranzer@linaro.org, kernel.max@enpas.org Subject: [RFC PATCH v3 10/13] Documentation: Add bootsplash main documentation Date: Wed, 17 Jan 2018 21:54:32 +0100 Message-Id: <20180117205435.2860-11-mstaudt@suse.de> X-Mailer: git-send-email 2.12.3 In-Reply-To: <20180117205435.2860-1-mstaudt@suse.de> References: <20180117205435.2860-1-mstaudt@suse.de> Sender: linux-fbdev-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fbdev@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Signed-off-by: Max Staudt --- .../ABI/testing/sysfs-platform-bootsplash | 11 + Documentation/bootsplash.rst | 285 +++++++++++++++++++++ MAINTAINERS | 2 + 3 files changed, 298 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 +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 + + +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 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