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