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   It is advised to add display# aliases to help the OS determine how
  30   to number things. If display# aliases are used, then if the simplefb
  31   node contains a display property then the /aliases/display# path
  32   must point to the display hw node the display property points to,
  33   otherwise it must point directly to the simplefb node.
  34
  35   If a simplefb node represents the preferred console for user
  36   interaction, then the chosen node stdout-path property should point
  37   to it, or to the primary display hw node, as with display#
  38   aliases. If display aliases are used then it should be set to the
  39   alias instead.
  40
  41   It is advised that devicetree files contain pre-filled, disabled
  42   framebuffer nodes, so that the firmware only needs to update the
  43   mode information and enable them. This way if e.g. later on support
  44   for more display clocks get added, the simplefb nodes will already
  45   contain this info and the firmware does not need to be updated.
  46
  47   If pre-filled framebuffer nodes are used, the firmware may need
  48   extra information to find the right node. In that case an extra
  49   platform specific compatible and platform specific properties should
  50   be used and documented.
  51
  52 properties:
  53   compatible:
  54     oneOf:
  55       - items:
  56           - enum:
  57               - apple,simple-framebuffer
  58               - allwinner,simple-framebuffer
  59               - amlogic,simple-framebuffer
  60           - const: simple-framebuffer
  61       - const: simple-framebuffer
  62
  63   reg:
  64     description: Location and size of the framebuffer memory
  65
  66   clocks:
  67     description: List of clocks used by the framebuffer.
  68
  69   power-domains:
  70     description: List of power domains used by the framebuffer.
  71
  72   width:
  73     $ref: /schemas/types.yaml#/definitions/uint32
  74     description: Width of the framebuffer in pixels
  75
  76   height:
  77     $ref: /schemas/types.yaml#/definitions/uint32
  78     description: Height of the framebuffer in pixels
  79
  80   stride:
  81     $ref: /schemas/types.yaml#/definitions/uint32
  82     description: Number of bytes of a line in the framebuffer
  83
  84   format:
  85     description: >
  86       Format of the framebuffer:
  87         * `a1r5g5b5` - 16-bit pixels, d[15]=a, d[14:10]=r, d[9:5]=g, d[4:0]=b
  88         * `a2r10g10b10` - 32-bit pixels, d[31:30]=a, d[29:20]=r, d[19:10]=g, d[9:0]=b
  89         * `a8b8g8r8` - 32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r
  90         * `a8r8g8b8` - 32-bit pixels, d[31:24]=a, d[23:16]=r, d[15:8]=g, d[7:0]=b
  91         * `r5g6b5` - 16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b
  92         * `r5g5b5a1` - 16-bit pixels, d[15:11]=r, d[10:6]=g, d[5:1]=b d[1:0]=a
  93         * `r8g8b8` - 24-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b
  94         * `x1r5g5b5` - 16-bit pixels, d[14:10]=r, d[9:5]=g, d[4:0]=b
  95         * `x2r10g10b10` - 32-bit pixels, d[29:20]=r, d[19:10]=g, d[9:0]=b
  96         * `x8r8g8b8` - 32-bit pixels, d[23:16]=r, d[15:8]=g, d[7:0]=b
  97     enum:
  98       - a1r5g5b5
  99       - a2r10g10b10
 100       - a8b8g8r8
 101       - a8r8g8b8
 102       - r5g6b5
 103       - r5g5b5a1
 104       - r8g8b8
 105       - x1r5g5b5
 106       - x2r10g10b10
 107       - x8r8g8b8
 108
 109   display:
 110     $ref: /schemas/types.yaml#/definitions/phandle
 111     description: Primary display hardware node
 112
 113   allwinner,pipeline:
 114     description: Pipeline used by the framebuffer on Allwinner SoCs
 115     enum:
 116       - de_be0-lcd0
 117       - de_be0-lcd0-hdmi
 118       - de_be0-lcd0-tve0
 119       - de_be1-lcd0
 120       - de_be1-lcd1-hdmi
 121       - de_fe0-de_be0-lcd0
 122       - de_fe0-de_be0-lcd0-hdmi
 123       - de_fe0-de_be0-lcd0-tve0
 124       - mixer0-lcd0
 125       - mixer0-lcd0-hdmi
 126       - mixer1-lcd1-hdmi
 127       - mixer1-lcd1-tve
 128
 129   amlogic,pipeline:
 130     description: Pipeline used by the framebuffer on Amlogic SoCs
 131     enum:
 132       - vpu-cvbs
 133       - vpu-hdmi
 134
 135 patternProperties:
 136   "^[a-zA-Z0-9-]+-supply$":
 137     $ref: /schemas/types.yaml#/definitions/phandle
 138     description:
 139       Regulators used by the framebuffer. These should be named
 140       according to the names in the device design.
 141
 142 required:
 143   # The binding requires also reg, width, height, stride and format,
 144   # but usually they will be filled by the bootloader.
 145   - compatible
 146
 147 allOf:
 148   - if:
 149       properties:
 150         compatible:
 151           contains:
 152             const: allwinner,simple-framebuffer
 153
 154     then:
 155       required:
 156         - allwinner,pipeline
 157
 158   - if:
 159       properties:
 160         compatible:
 161           contains:
 162             const: amlogic,simple-framebuffer
 163
 164     then:
 165       required:
 166         - amlogic,pipeline
 167
 168
 169 additionalProperties: false
 170
 171 examples:
 172   - |
 173     / {
 174         compatible = "foo";
 175         model = "foo";
 176         #address-cells = <1>;
 177         #size-cells = <1>;
 178
 179         chosen {
 180             #address-cells = <1>;
 181             #size-cells = <1>;
 182             framebuffer0: framebuffer@1d385000 {
 183                 compatible = "allwinner,simple-framebuffer", "simple-framebuffer";
 184                 allwinner,pipeline = "de_be0-lcd0";
 185                 reg = <0x1d385000 3840000>;
 186                 width = <1600>;
 187                 height = <1200>;
 188                 stride = <3200>;
 189                 format = "r5g6b5";
 190                 clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>;
 191                 lcd-supply = <&reg_dc1sw>;
 192                 display = <&lcdc0>;
 193             };
 194         };
 195     };
 196
 197 ...