From patchwork Wed Oct 25 12:46:01 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: 'Max Staudt X-Patchwork-Id: 10026625 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 12A20601E8 for ; Wed, 25 Oct 2017 12:47:14 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0ED1B28AB2 for ; Wed, 25 Oct 2017 12:47:14 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 01FDC28B63; Wed, 25 Oct 2017 12:47: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 3FB9F28AB2 for ; Wed, 25 Oct 2017 12:47:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751950AbdJYMqo (ORCPT ); Wed, 25 Oct 2017 08:46:44 -0400 Received: from mx2.suse.de ([195.135.220.15]:36192 "EHLO mx2.suse.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751920AbdJYMqg (ORCPT ); Wed, 25 Oct 2017 08:46:36 -0400 X-Virus-Scanned: by amavisd-new at test-mx.suse.de Received: from relay2.suse.de (charybdis-ext.suse.de [195.135.220.254]) by mx2.suse.de (Postfix) with ESMTP id 96029AD68; Wed, 25 Oct 2017 12:46:28 +0000 (UTC) From: Max Staudt To: b.zolnierkie@samsung.com, linux-fbdev@vger.kernel.org Cc: mstaudt@suse.de, tiwai@suse.com, oneukum@suse.com, msrb@suse.com, sndirsch@suse.com, michal@markovi.net, linux-kernel@vger.kernel.org Subject: [RFC 13/14] bootsplash: Add main documentation Date: Wed, 25 Oct 2017 14:46:01 +0200 Message-Id: <20171025124602.28292-14-mstaudt@suse.de> X-Mailer: git-send-email 2.12.3 In-Reply-To: <20171025124602.28292-1-mstaudt@suse.de> References: <20171025124602.28292-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 Reviewed-by: Oliver Neukum --- Documentation/fb/bootsplash.txt | 169 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 Documentation/fb/bootsplash.txt diff --git a/Documentation/fb/bootsplash.txt b/Documentation/fb/bootsplash.txt new file mode 100644 index 000000000000..e2b7c956e6c2 --- /dev/null +++ b/Documentation/fb/bootsplash.txt @@ -0,0 +1,169 @@ +What is the Linux bootsplash? +============================== + +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. + + + +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 holding /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 + + + +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. + +drivers/tty/vt/vt_ioctl.c + + vt_ioctl() will call bootsplash_disable() when a graphical application + such as the X server is started (i.e. when setting the VT to KD_GRAPHICS). + + + +Command line arguments +======================= + +bool bootsplash.enable Whether to show a splash screen during boot + (default: off) + +string bootsplash.filename Which file in the initrd to load + (default: /bootsplash) + + + +sysfs run-time configuration +============================= + +bool /sys/devices/platform/bootsplash.0/enabled Enable/disable + +trigger /sys/devices/platform/bootsplash.0/drop_splash Unload splash data + and free memory + + +Kconfig +======== + +bool BOOTSPLASH Whether to compile in bootsplash support + (depends on fbcon compiled in, i.e. + FRAMEBUFFER_CONSOLE=y) + +string BOOTSPLASH_FILE Which file in the initrd to load + (default: /bootsplash) + + + +Bootsplash file format +======================= + +A file specified in the kernel configuration as CONFIG_BOOTSPLASH_FILE or +specified on the command line as bootsplash.filename will be loaded and +displayed as soon as fbcon is initialized. + + +There are 3 main blocks in each file: + + - one File header + - n Picture headers + - m (Blob header + payload) blocks + + +The 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" + -> The file format version (for incompatible updates, hopefully never) + -> The background color + -> Number of picture and blob blocks + -> Animation speed (we only allow one speed 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. + + +A note about alignment: + +The bootsplash file is designed to be loaded into memory as-is (plus +performing an endianness conversion before further processing). + +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. + + +Please see drivers/video/fbdev/core/bootsplash_file.h for further details and +possible values in the file.