[PATCH v3 2/7] dt-bindings: display: add a device tree supplied boot logo

[Max Pedraza <maximpedraza@gmail.com>]

Embedded products frequently need a product specific boot logo. Today that
means pointing CONFIG_LOGO_LINUX_CLUT224_FILE at a different image, which
bakes it into the kernel image: a change of branding, or a second product
sharing the same board support package, requires a separate kernel build,
and requalifying that kernel for what is a cosmetic change.

Add a binding for a "boot-logo-clut224" node, which carries the logo
in the same paletted format the built-in CLUT224 logos already use, plus a
few optional properties describing where on the screen it is drawn.

The node lives under /chosen because a logo is configuration handed over by
firmware rather than a description of the hardware. Open Firmware, which
the device tree descends from, carried a boot logo in the same spirit as
the oem-logo variable under /options, and simple-framebuffer nodes live
under /chosen today for the same reason.

The palette size is derived from the length of the "clut" property rather
than spelled out separately, and "data" holds plain palette indices; the
32 entry offset the frame buffer layer reserves for the console is an
implementation detail and is applied by the kernel, not by the binding.

"logo-position" takes -1 on an axis to mean centre on that axis rather than
carrying a separate boolean for it. A boolean can only centre both axes or
neither, and next to explicit coordinates it would have to override them
silently when a device tree gave both.

A rotation turns the logo, not the screen. "logo-position" and
"logo-offset" are screen pixels whatever "logo-rotation" says, and a
quarter turn only changes how much room the logo takes up. Placing the
logo in a frame that turns with it would make the same pair of
coordinates mean different places on the same panel, decided by a
property that is meant to describe the image.

Every coordinate is bounded. The kernel clamps them anyway, since it cannot
trust a device tree, but a value that cannot possibly be meant is worth
catching in dtbs_check rather than on the panel.

Signed-off-by: Max Pedraza <maximpedraza@gmail.com>
---
 .../bindings/display/boot-logo-clut224.yaml   | 135 ++++++++++++++++++
 MAINTAINERS                                   |   1 +
 2 files changed, 136 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/display/boot-logo-clut224.yaml

diff --git a/Documentation/devicetree/bindings/display/boot-logo-clut224.yaml b/Documentation/devicetree/bindings/display/boot-logo-clut224.yaml
new file mode 100644
index 0000000000..9dc3471763
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/boot-logo-clut224.yaml
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/display/boot-logo-clut224.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Boot logo supplied by the device tree
+
+maintainers:
+  - Max Pedraza <maximpedraza@gmail.com>
+
+description: |
+  Embedded systems commonly need a product specific boot logo. Today that
+  means pointing CONFIG_LOGO_LINUX_CLUT224_FILE at a different image, which
+  bakes it into the kernel image: changing the logo means building and
+  deploying a new kernel.
+
+  This node lets the boot logo be described by the device tree instead, so that
+  a single kernel image can serve several products, or several revisions of the
+  same product, that only differ in branding.
+
+  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. Open Firmware, which the device tree descends from, carried
+  a boot logo in the same spirit as the oem-logo variable under /options.
+
+  The image is stored in the same paletted format the in-kernel CLUT224 logos
+  use: a palette of at most 224 RGB entries plus one palette index per pixel.
+
+properties:
+  $nodename:
+    const: logo
+
+  compatible:
+    const: boot-logo-clut224
+
+  width:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Logo width in pixels.
+    minimum: 1
+    maximum: 65535
+
+  height:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Logo height in pixels.
+    minimum: 1
+    maximum: 65535
+
+  clut:
+    $ref: /schemas/types.yaml#/definitions/uint8-array
+    description:
+      Colour lookup table, as consecutive red, green and blue bytes per entry.
+      The number of entries is derived from the property length and must not
+      exceed 224.
+    minItems: 3
+    maxItems: 672
+
+  data:
+    $ref: /schemas/types.yaml#/definitions/uint8-array
+    description:
+      One byte per pixel, left to right and top to bottom, each byte being an
+      index into the colour lookup table. The property length must be equal to
+      width multiplied by height.
+
+  logo-position:
+    $ref: /schemas/types.yaml#/definitions/int32-array
+    description:
+      X and Y coordinates, in pixels, of the top left corner of the logo.
+      A value of -1 on an axis centres the logo on that axis instead.
+      Defaults to the top left corner of the screen.
+    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 logo has been
+      placed.
+      Mostly useful together with a centred axis, to land the logo somewhere
+      other than the middle of a panel whose usable area is not its centre.
+    items:
+      - description: X displacement
+        minimum: -65535
+        maximum: 65535
+      - description: Y displacement
+        minimum: -65535
+        maximum: 65535
+
+  logo-rotation:
+    $ref: /schemas/types.yaml#/definitions/string
+    description:
+      Rotation applied to the logo before it is drawn. It turns the logo and
+      not the screen, so a quarter turn swaps how much room the logo takes
+      up, but logo-position and logo-offset stay in screen pixels either
+      way.
+    enum: [none, cw, ccw, ud]
+    default: none
+
+required:
+  - compatible
+  - width
+  - height
+  - clut
+  - data
+
+additionalProperties: false
+
+examples:
+  - |
+    // A 4x2 logo using three colours, centred on both axes.
+    / {
+        compatible = "foo";
+        model = "foo";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        chosen {
+            logo {
+                compatible = "boot-logo-clut224";
+                width = <4>;
+                height = <2>;
+                clut = /bits/ 8 <0xff 0x00 0x00
+                                 0x00 0xff 0x00
+                                 0x00 0x00 0xff>;
+                data = /bits/ 8 <0x00 0x01 0x01 0x00
+                                 0x02 0x00 0x00 0x02>;
+                logo-position = <(-1) (-1)>;
+            };
+        };
+    };
diff --git a/MAINTAINERS b/MAINTAINERS
index c241444789..804a48e9bc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10339,6 +10339,7 @@ L:	dri-devel@lists.freedesktop.org
 S:	Maintained
 Q:	http://patchwork.kernel.org/project/linux-fbdev/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/deller/linux-fbdev.git
+F:	Documentation/devicetree/bindings/display/boot-logo-clut224.yaml
 F:	Documentation/fb/
 F:	drivers/video/
 F:	include/linux/fb.h
-- 
2.39.5