The overview only said that the client draws a colour or an image. By now the image can come from four places in a set order, be placed and turned, and every part of that can be overridden from the command line, each parameter for its own part only. Write it down: the sources and their order, the image format, placement and rotation, the background, every parameter with its format, and what a parameter given alone keeps from the image source.
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 clear it, 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 | 78 +++++++++++++++++++++++++++- 2 files changed, 83 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 8d056edfee56..85083337870c 100644 --- a/drivers/gpu/drm/clients/drm_splash.c +++ b/drivers/gpu/drm/clients/drm_splash.c @@ -37,7 +37,83 @@ * 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 stays + * until userspace takes the display over. + * + * 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 40 byte BITMAPINFOHEADER, 24 bits per pixel and no + * compression. It comes from the first of these that provides one: + * + * 1. a BMP loaded as firmware and named on the command line with + * ``drm_client_lib.splash_bmp=``; ``splash_bmp=none`` asks for no image at + * all, and a named file that is missing gives no image rather than falling + * back to the sources below; + * 2. a "boot-logo" node under ``/chosen`` in the device tree, carrying the BMP + * itself or pointing at a reserved memory region the bootloader loaded it + * into (see Documentation/devicetree/bindings/display/boot-logo.yaml); + * 3. the EFI BGRT, the image the firmware showed; + * 4. ``drm_splash.bmp`` 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, so a bootloader that loads no image there has + * to clear it: the kernel cannot tell a stale image from a fresh one. + * + * Placement + * --------- + * + * The image is placed at a position in screen 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 screen 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. A BGRT image is + * placed at the table offsets and turned as its orientation bits say, the + * offsets then being given on the upright screen. Any other image is centred + * and upright. + * + * 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. + * + * Command line + * ------------ + * + * What the command line gives wins over every source, each parameter only for + * what it says, and only when it is given: + * + * ``drm_client_lib.splash_bmp=NAME`` + * BMP to load as firmware, or ``none`` for no image. + * ``drm_client_lib.splash_color=0xRRGGBB`` + * background color, whatever the image. + * ``drm_client_lib.splash_pos=X,Y`` + * position; ``-1,-1`` centres, ``-1,183`` centres horizontally only. + * ``drm_client_lib.splash_offset=DX,DY`` + * offset added to the position, for instance ``0,80``. + * ``drm_client_lib.splash_rotation=DEGREES`` + * 0, 90, 180 or 270, counter clockwise. + * + * Positions take both values, or are ignored with a warning. Since each + * parameter only replaces its own part, the rest keeps coming from the image + * source: ``splash_offset=`` alone moves the image from where the source puts + * it, centred for a BMP loaded as firmware, and ``splash_pos=`` alone keeps a + * device tree node's "logo-offset". Give both to place the image exactly. A + * BGRT image placed from the command line is placed in screen pixels like any + * other: the table offsets are then not used. */ /* -- 2.39.5
