[PATCH RFC v4 06/13] dt-bindings: display: add a boot logo node under /chosen
From: Màxim Pedraza Padilla
Date: Thu Oct 01 2026 - 16:02:24 EST
Products built on the same board often differ only in branding. On UEFI
systems the firmware hands the operating system its boot logo through
the ACPI BGRT; a device tree system has no such table, so today the logo
is built into the kernel, and each product needs its own kernel image.
With U-Boot's Falcon mode the device tree is the only thing that reaches
the kernel, so it is also the only place the logo can come from.
Add a "boot-logo" node under /chosen. The node lives there because a
logo is configuration handed over by firmware rather than a description
of the hardware, as simple-framebuffer nodes already are.
The image is a BMP with 24 bits per pixel and no compression, the
format of the BGRT image, so that one file serves the firmware splash,
a BMP loaded as firmware and this node alike. It is carried either in
an "image" property, which dtc fills in from the file with /incbin/, or
in a reserved memory region the bootloader loaded it into, named by
"memory-region". Exactly one of the two must be present.
"logo-position" takes -1 on an axis to mean centre on that axis, which
is the only way to say it when the device tree does not know the image
size, and "logo-offset" is added afterwards. "rotation" counts degrees
counter clockwise, as for panels, and turns the image rather than the
screen, so position and offset stay in screen pixels. The optional
"background-color" goes with the image, since a logo designed for one
background looks wrong on another.
Assisted-by: Claude:claude-opus-5-5
Signed-off-by: Màxim Pedraza Padilla <maximpedraza@xxxxxxxxx>
---
.../bindings/display/boot-logo.yaml | 151 ++++++++++++++++++
MAINTAINERS | 1 +
2 files changed, 152 insertions(+)
create mode 100644 Documentation/devicetree/bindings/display/boot-logo.yaml
diff --git a/Documentation/devicetree/bindings/display/boot-logo.yaml b/Documentation/devicetree/bindings/display/boot-logo.yaml
new file mode 100644
index 000000000000..b540a04deb78
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/boot-logo.yaml
@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/boot-logo.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Boot logo supplied by the device tree
+
+maintainers:
+ - Francesco Valla <francesco@xxxxxxxx>
+ - Màxim Pedraza Padilla <maximpedraza@xxxxxxxxx>
+
+description: |
+ An image for the operating system to show on the display while it boots,
+ handed over by the firmware together with where and how to show it.
+
+ Products built on the same board often differ only in branding. Carrying
+ the logo in the device tree lets a single kernel image serve all of them,
+ each booting with its own device tree, and it works where the device tree
+ is the only thing that reaches the kernel, as with U-Boot's Falcon mode.
+ It plays the part the ACPI BGRT plays on UEFI systems.
+
+ Since a logo is configuration rather than a description of the hardware,
+ the node lives under /chosen, next to the other things firmware hands to
+ the operating system.
+
+ The image is a BMP file with a 40 byte BITMAPINFOHEADER, 24 bits per pixel
+ and no compression, the format of the BGRT image. It is carried either in
+ the node itself or in a reserved memory region the bootloader loaded it
+ into, never both.
+
+properties:
+ $nodename:
+ const: logo
+
+ compatible:
+ const: boot-logo
+
+ image:
+ $ref: /schemas/types.yaml#/definitions/uint8-array
+ description:
+ The BMP file itself, byte for byte, which dtc can fill in from the file
+ with /incbin/. The device tree stays in memory for as long as the
+ system runs, so this is meant for small images; larger ones belong in
+ a reserved memory region.
+
+ memory-region:
+ maxItems: 1
+ description: |
+ Reserved memory region the bootloader loaded the BMP file into, starting
+ at the beginning of the region. The BMP header says how much of the
+ region is image.
+
+ This keeps the image out of the device tree, so that it can be changed
+ without rebuilding the device tree, for instance by loading it from a
+ partition of its own that userspace can update.
+
+ Memory keeps its contents across a reset, and may even across a short
+ power cycle, so a bootloader that loads no image into the region has to
+ clear it: the operating system cannot tell a stale image from a fresh
+ one.
+
+ logo-position:
+ $ref: /schemas/types.yaml#/definitions/int32-array
+ description:
+ X and Y coordinates, in screen pixels, of the top left corner of the
+ image once it has been rotated. A value of -1 on an axis centres the
+ image on that axis instead, which is the only way to say it when the
+ device tree does not know the image size, as with a memory region.
+ Defaults to centring on both axes.
+ items:
+ - description: X coordinate, or -1 to centre horizontally
+ minimum: -1
+ maximum: 65535
+ - description: Y coordinate, or -1 to centre vertically
+ minimum: -1
+ maximum: 65535
+
+ logo-offset:
+ $ref: /schemas/types.yaml#/definitions/int32-array
+ description:
+ X and Y displacement, in screen pixels, applied after the image has been
+ placed. Mostly useful together with a centred axis, to land the image
+ somewhere other than the middle of a panel whose visible area is not
+ the middle of the mode.
+ items:
+ - description: X displacement
+ minimum: -65535
+ maximum: 65535
+ - description: Y displacement
+ minimum: -65535
+ maximum: 65535
+
+ rotation:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Rotation applied to the image before it is shown, in degrees counter
+ clockwise, as for the rotation property of panels. It turns the image
+ and not the screen, so a quarter turn swaps how much room the image
+ takes up, but logo-position and logo-offset stay in screen pixels
+ either way.
+ enum: [0, 90, 180, 270]
+ default: 0
+
+ background-color:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ Colour of the rest of the screen, as 0xRRGGBB. When absent, the
+ operating system uses its own default.
+ maximum: 0xffffff
+
+required:
+ - compatible
+
+# The image lives either in the node or in a reserved memory region,
+# never both and never neither.
+oneOf:
+ - required:
+ - image
+ - required:
+ - memory-region
+
+additionalProperties: false
+
+examples:
+ - |
+ // A 2x1 image, red and blue, centred and 120 pixels below the middle
+ / {
+ compatible = "foo";
+ model = "foo";
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ chosen {
+ logo {
+ compatible = "boot-logo";
+ /* Normally: image = /incbin/("logo.bmp"); */
+ image = /bits/ 8 <0x42 0x4d 0x3e 0x00 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x36 0x00 0x00 0x00 0x28 0x00
+ 0x00 0x00 0x02 0x00 0x00 0x00 0x01 0x00
+ 0x00 0x00 0x01 0x00 0x18 0x00 0x00 0x00
+ 0x00 0x00 0x08 0x00 0x00 0x00 0x13 0x0b
+ 0x00 0x00 0x13 0x0b 0x00 0x00 0x00 0x00
+ 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00
+ 0xff 0xff 0x00 0x00 0x00 0x00>;
+ logo-position = <(-1) (-1)>;
+ logo-offset = <0 120>;
+ background-color = <0x1e1e28>;
+ };
+ };
+ };
diff --git a/MAINTAINERS b/MAINTAINERS
index 44730414e5df..9f057fdb3bdb 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9161,6 +9161,7 @@ M: Màxim Pedraza Padilla <maximpedraza@xxxxxxxxx>
L: dri-devel@xxxxxxxxxxxxxxxxxxxxx
S: Maintained
T: git https://gitlab.freedesktop.org/drm/misc/kernel.git
+F: Documentation/devicetree/bindings/display/boot-logo.yaml
F: drivers/gpu/drm/clients/drm_splash.c
DRM TTM SUBSYSTEM
--
2.39.5