Documentation/devicetree/bindings/display/simple-framebuffer.yaml

   1 # SPDX-License-Identifier: GPL-2.0
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/display/simple-framebuffer.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: Simple Framebuffer
   8
   9 maintainers:
  10   - Hans de Goede <hdegoede@redhat.com>
  11
  12 description: |+
  13   A simple frame-buffer describes a frame-buffer setup by firmware or
  14   the bootloader, with the assumption that the display hardware has
  15   already been set up to scan out from the memory pointed to by the
  16   reg property.
  17
  18   Since simplefb nodes represent runtime information they must be
  19   sub-nodes of the chosen node (*). Simplefb nodes must be named
  20   framebuffer@<address>.
  21
  22   If the devicetree contains nodes for the display hardware used by a
  23   simplefb, then the simplefb node must contain a property called
  24   display, which contains a phandle pointing to the primary display
  25   hw node, so that the OS knows which simplefb to disable when handing
  26   over control to a driver for the real hardware. The bindings for the
  27   hw nodes must specify which node is considered the primary node.
  28
  29   If a panel node is given, then the driver uses this to configure the
  30   physical width and height of the display. If no panel node is given,
  31   then the driver uses the width and height properties of the simplefb
  32   node to estimate it.
  33
  34   It is advised to add display# aliases to help the OS determine how
  35   to number things. If display# aliases are used, then if the simplefb
  36   node contains a display property then the /aliases/display# path
  37   must point to the display hw node the display property points to,
  38   otherwise it must point directly to the simplefb node.
  39
  40   If a simplefb node represents the preferred console for user
  41   interaction, then the chosen node stdout-path property should point
  42   to it, or to the primary display hw node, as with display#
  43   aliases. If display aliases are used then it should be set to the
  44   alias instead.
  45
  46   It is advised that devicetree files contain pre-filled, disabled
  47   framebuffer nodes, so that the firmware only needs to update the
  48   mode information and enable them. This way if e.g. later on support
  49   for more display clocks get added, the simplefb nodes will already
  50   contain this info and the firmware does not need to be updated.
  51
  52   If pre-filled framebuffer nodes are used, the firmware may need
  53   extra information to find the right node. In that case an extra
  54   platform specific compatible and platform specific properties should
  55   be used and documented.
  56
  57 properties:
  58   compatible:
  59     oneOf:
  60       - items:
  61           - enum:
  62               - apple,simple-framebuffer
  63               - allwinner,simple-framebuffer
  64               - amlogic,simple-framebuffer
  65           - const: simple-framebuffer
  66       - const: simple-framebuffer
  67
  68   reg:
  69     description: Location and size of the framebuffer memory
  70
  71   memory-region:
  72     maxItems: 1
  73     description: Phandle to a node describing the memory to be used for the
  74       framebuffer. If present, overrides the "reg" property (if one exists).
  75
  76   clocks:
  77     description: List of clocks used by the framebuffer.
  78
  79   power-domains:
  80     description: List of power domains used by the framebuffer.
  81
  82   width:
  83     $ref: /schemas/types.yaml#/definitions/uint32
  84     description: Width of the framebuffer in pixels
  85
  86   height:
  87     $ref: /schemas/types.yaml#/definitions/uint32
  88     description: Height of the framebuffer in pixels
  89
  90   stride:
  91     $ref: /schemas/types.yaml#/definitions/uint32
  92     description: Number of bytes of a line in the framebuffer
  93
  94   format:
  95     description: >
  96       Format of the framebuffer:
  97         * `a1r5g5b5` - 16-bit pixels, d[15]=a, d[14:10]=r, d[9:5]=g, d[4:0]=b
  98         * `a2r10g10b10` - 32-bit pixels, d[31:30]=a, d[29:20]=r, d[19:10]=g, d[9:0]=b
  99         * `a8b8g8r8` - 32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r
 100         * `a8r8g8b8` - 32-bit pixels, d[31:24]=a, d[23:16]=r, d[15:8]=g, d[7:0]=b
 101         * `r5g6b5` - 16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b
 102         * `r5g5b5a1` - 16-bit pixels, d[15:11]=r, d[10:6]=g, d[5:1]=b d[1:0]=a
 103         * `r8g8b8` - 24-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b
 104         * `x1r5g5b5` - 16-bit pixels, d[14:10]=r, d[9:5]=g, d[4:0]=b
 105         * `x2r10g10b10` - 32-bit pixels, d[29:20]=r, d[19:10]=g, d[9:0]=b
 106         * `x8r8g8b8` - 32-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b
 107         * `x8b8g8r8` - 32-bit pixels, d[23:16]=b, d[15:8]=g, d[7:0]=r
 108     enum:
 109       - a1r5g5b5
 110       - a2r10g10b10
 111       - a8b8g8r8
 112       - a8r8g8b8
 113       - r5g6b5
 114       - r5g5b5a1
 115       - r8g8b8
 116       - x1r5g5b5
 117       - x2r10g10b10
 118       - x8r8g8b8
 119       - x8b8g8r8
 120
 121   display:
 122     $ref: /schemas/types.yaml#/definitions/phandle
 123     description: Primary display hardware node
 124
 125   panel:
 126     $ref: /schemas/types.yaml#/definitions/phandle
 127     description: Display panel node
 128
 129   allwinner,pipeline:
 130     description: Pipeline used by the framebuffer on Allwinner SoCs
 131     enum:
 132       - de_be0-lcd0
 133       - de_be0-lcd0-hdmi
 134       - de_be0-lcd0-tve0
 135       - de_be1-lcd0
 136       - de_be1-lcd1-hdmi
 137       - de_fe0-de_be0-lcd0
 138       - de_fe0-de_be0-lcd0-hdmi
 139       - de_fe0-de_be0-lcd0-tve0
 140       - mixer0-lcd0
 141       - mixer0-lcd0-hdmi
 142       - mixer1-lcd1-hdmi
 143       - mixer1-lcd1-tve
 144
 145   amlogic,pipeline:
 146     description: Pipeline used by the framebuffer on Amlogic SoCs
 147     enum:
 148       - vpu-cvbs
 149       - vpu-hdmi
 150
 151 patternProperties:
 152   "^[a-zA-Z0-9-]+-supply$":
 153     $ref: /schemas/types.yaml#/definitions/phandle
 154     description:
 155       Regulators used by the framebuffer. These should be named
 156       according to the names in the device design.
 157
 158 required:
 159   # The binding requires also reg, width, height, stride and format,
 160   # but usually they will be filled by the bootloader.
 161   - compatible
 162
 163 allOf:
 164   - if:
 165       properties:
 166         compatible:
 167           contains:
 168             const: allwinner,simple-framebuffer
 169
 170     then:
 171       required:
 172         - allwinner,pipeline
 173
 174   - if:
 175       properties:
 176         compatible:
 177           contains:
 178             const: amlogic,simple-framebuffer
 179
 180     then:
 181       required:
 182         - amlogic,pipeline
 183
 184
 185 additionalProperties: false
 186
 187 examples:
 188   - |
 189     / {
 190         compatible = "foo";
 191         model = "foo";
 192         #address-cells = <1>;
 193         #size-cells = <1>;
 194
 195         chosen {
 196             #address-cells = <1>;
 197             #size-cells = <1>;
 198             framebuffer0: framebuffer@1d385000 {
 199                 compatible = "allwinner,simple-framebuffer", "simple-framebuffer";
 200                 allwinner,pipeline = "de_be0-lcd0";
 201                 reg = <0x1d385000 3840000>;
 202                 width = <1600>;
 203                 height = <1200>;
 204                 stride = <3200>;
 205                 format = "r5g6b5";
 206                 clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>;
 207                 lcd-supply = <&reg_dc1sw>;
 208                 display = <&lcdc0>;
 209             };
 210         };
 211     };
 212
 213 ...