[PATCH 1/4] dt-bindings: display: panel: document panel-id

[Rob Clark <robdclark@gmail.com>]

From: Rob Clark <robdclark@chromium.org>

For devices that have one of several possible panels installed, the
panel-id property gives firmware a generic way to locate and enable the
panel node corresponding to the installed panel.  Example of how to use
this property:

    ivo_panel {
        compatible = "ivo,m133nwf4-r0";
        panel-id = <0xc5>;
        status = "disabled";

        ports {
            port {
                ivo_panel_in_edp: endpoint {
                    remote-endpoint = <&sn65dsi86_out_ivo>;
                };
            };
        };
    };

    boe_panel {
        compatible = "boe,nv133fhm-n61";
        panel-id = <0xc4>;
        status = "disabled";

        ports {
            port {
                boe_panel_in_edp: endpoint {
                    remote-endpoint = <&sn65dsi86_out_boe>;
                };
            };
        };
    };

    sn65dsi86: bridge@2c {
        compatible = "ti,sn65dsi86";

        ports {
            #address-cells = <1>;
            #size-cells = <0>;

            port@0 {
                reg = <0>;
                sn65dsi86_in_a: endpoint {
                    remote-endpoint = <&dsi0_out>;
                };
            };

            port@1 {
                reg = <1>;

                sn65dsi86_out_boe: endpoint@c4 {
                    remote-endpoint = <&boe_panel_in_edp>;
                };

                sn65dsi86_out_ivo: endpoint@c5 {
                    remote-endpoint = <&ivo_panel_in_edp>;
                };
            };
        };
    };

Signed-off-by: Rob Clark <robdclark@chromium.org>
---
 .../bindings/display/panel/panel-common.yaml  | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/Documentation/devicetree/bindings/display/panel/panel-common.yaml b/Documentation/devicetree/bindings/display/panel/panel-common.yaml
index ef8d8cdfcede..6113319b91dd 100644
--- a/Documentation/devicetree/bindings/display/panel/panel-common.yaml
+++ b/Documentation/devicetree/bindings/display/panel/panel-common.yaml
@@ -75,6 +75,32 @@ properties:
       in the device graph bindings defined in
       Documentation/devicetree/bindings/graph.txt.
 
+  panel-id:
+    description:
+      To support the case where one of several different panels can be installed
+      on a device, the panel-id property can be used by the firmware to identify
+      which panel should have it's status changed to "ok".  This property is not
+      used by the HLOS itself.
+
+      For a device with multiple potential panels, a node for each potential
+      should be defined with status = "disabled", and an appropriate panel-id
+      property.  The video data producer should be setup with endpoints going to
+      each possible panel.  The firmware will find the dt node with a panel-id
+      matching the actual panel installed, and change it's status to "ok".
+
+      The exact method the firmware uses to determine the panel-id of the installed
+      panel is outside the scope of this binding, but a few examples are
+
+      1) u-boot module reading a value from a u-boot env var
+      2) EFI driver module reading a value from an EFI variable
+      3) device specific firmware reading some device specific GPIOs or
+         e-fuse
+
+      The panel-id values are an opaque integer.  They can be sparse.  The only
+      important thing is that each possible panel in the system has a unique
+      panel-id, and that the values configured in the device's DTB match the
+      values that the firmware is looking for.
+
   ddc-i2c-bus:
     $ref: /schemas/types.yaml#/definitions/phandle
     description:
-- 
2.23.0