The overview only said that the client draws a colour or an image. By now the image can come from three places in a set order, and be placed and turned. Write it down: the sources and their order, the image format, placement and rotation, and the background.
Also note that the splash rules out fbdev emulation on the same device, and that a bootloader that loads no image into a reserved region has to disable or remove the node, since the region can keep the previous image across a reset and even a short power cycle. Pull the overview into Documentation/gpu/drm-client.rst, which covers the in-kernel clients, so that it is published. Assisted-by: Claude:claude-opus-5-5 Signed-off-by: Màxim Pedraza Padilla <[email protected]> --- Documentation/gpu/drm-client.rst | 6 +++ drivers/gpu/drm/clients/drm_splash.c | 61 +++++++++++++++++++++++++++- 2 files changed, 66 insertions(+), 1 deletion(-) diff --git a/Documentation/gpu/drm-client.rst b/Documentation/gpu/drm-client.rst index cbcfe30de777..a58d6440d9f2 100644 --- a/Documentation/gpu/drm-client.rst +++ b/Documentation/gpu/drm-client.rst @@ -16,3 +16,9 @@ Kernel clients .. kernel-doc:: drivers/gpu/drm/drm_client_event.c :export: + +Splash client +============= + +.. kernel-doc:: drivers/gpu/drm/clients/drm_splash.c + :doc: overview diff --git a/drivers/gpu/drm/clients/drm_splash.c b/drivers/gpu/drm/clients/drm_splash.c index d3ed53cde0f5..0fc72a3fe989 100644 --- a/drivers/gpu/drm/clients/drm_splash.c +++ b/drivers/gpu/drm/clients/drm_splash.c @@ -40,7 +40,66 @@ * DOC: overview * * This is a simple graphic bootsplash, able to display either a plain color or - * a static image. + * a static image. It draws once the display driver has registered, and again + * on every hotplug, on the outputs there are then, until userspace takes the + * display over; when userspace lets it go, the splash is shown again. + * + * It is selected with ``drm_client_lib.active=splash`` or + * CONFIG_DRM_CLIENT_DEFAULT_SPLASH. A device has a single in-kernel client, so + * with the splash there is no fbdev emulation: no ``/dev/fb0`` and no + * framebuffer console. + * + * Image sources + * ------------- + * + * The image is a BMP with a BITMAPINFOHEADER, or its V4 or V5 extension, + * 24 bits per pixel and no compression. It comes from the first of these that + * is present, each built in with its CONFIG_DRM_CLIENT_SPLASH_SRC_* option; if + * that one then fails to load, only the background is drawn: + * + * 1. a node compatible with "boot-logo" under ``/chosen`` in the device tree, + * carrying the BMP itself or pointing at a reserved memory region the + * bootloader loaded it into, if that region can be mapped (see + * Documentation/devicetree/bindings/display/boot-logo.yaml); + * 2. the EFI BGRT, the image the firmware showed; + * 3. the BMP named by CONFIG_DRM_CLIENT_SPLASH_BMP_NAME, ``drm_splash.bmp`` by + * default, loaded as firmware, for instance built into the kernel with + * CONFIG_EXTRA_FIRMWARE. + * + * With none of them, only the background is drawn. + * + * A reserved memory region keeps its contents across a reset, and may even + * across a short power cycle, and the kernel cannot tell a stale image from a + * fresh one: a bootloader that loads no image there disables the node, or + * removes it. + * + * Placement + * --------- + * + * Everything is given as the screen is seen: once turned as its connector + * needs, for a panel mounted turned (the panel's orientation) or as asked + * with video=...,rotate=. The plane turns it in hardware when it can, and the + * splash turns its buffer in software otherwise, as fbdev does with the + * console. A panel mounted turned is described on the panel, not here. + * + * The image is placed at a position in pixels, where -1 centres it on that + * axis, and an offset is added afterwards; the result is clamped so that the + * whole image stays on screen. A rotation of 90, 180 or 270 degrees counter + * clockwise turns the image and not the screen: position and offset stay in + * the same pixels, and a quarter turn only swaps how much room the image + * takes up. + * + * A device tree image is placed and turned as its node says, and any other + * image is centred and upright. A BGRT image is the exception to the above: it + * is drawn at the table offsets on the screen the firmware drew it on, + * unturned but for the table's orientation bits. + * + * Background + * ---------- + * + * The rest of the screen is filled with the node's "background-color" for a + * device tree image, and with CONFIG_DRM_CLIENT_SPLASH_BACKGROUND_COLOR + * otherwise. */ /* -- 2.39.5
