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           - allwinner,simple-framebuffer
  58           - amlogic,simple-framebuffer
  59       - const: simple-framebuffer
  60
  61   reg:
  62     description: Location and size of the framebuffer memory
  63
  64   clocks:
  65     description: List of clocks used by the framebuffer.
  66
  67   power-domains:
  68     description: List of power domains used by the framebuffer.
  69
  70   width:
  71     $ref: /schemas/types.yaml#/definitions/uint32
  72     description: Width of the framebuffer in pixels
  73
  74   height:
  75     $ref: /schemas/types.yaml#/definitions/uint32
  76     description: Height of the framebuffer in pixels
  77
  78   stride:
  79     $ref: /schemas/types.yaml#/definitions/uint32
  80     description: Number of bytes of a line in the framebuffer
  81
  82   format:
  83     description: >
  84       Format of the framebuffer:
  85         * `a8b8g8r8` - 32-bit pixels, d[31:24]=a, d[23:16]=b, d[15:8]=g, d[7:0]=r
  86         * `r5g6b5` - 16-bit pixels, d[15:11]=r, d[10:5]=g, d[4:0]=b
  87     enum:
  88       - a8b8g8r8
  89       - r5g6b5
  90
  91   display:
  92     $ref: /schemas/types.yaml#/definitions/phandle
  93     description: Primary display hardware node
  94
  95   allwinner,pipeline:
  96     description: Pipeline used by the framebuffer on Allwinner SoCs
  97     enum:
  98       - de_be0-lcd0
  99       - de_be0-lcd0-hdmi
 100       - de_be0-lcd0-tve0
 101       - de_be1-lcd0
 102       - de_be1-lcd1-hdmi
 103       - de_fe0-de_be0-lcd0
 104       - de_fe0-de_be0-lcd0-hdmi
 105       - de_fe0-de_be0-lcd0-tve0
 106       - mixer0-lcd0
 107       - mixer0-lcd0-hdmi
 108       - mixer1-lcd1-hdmi
 109       - mixer1-lcd1-tve
 110
 111   amlogic,pipeline:
 112     description: Pipeline used by the framebuffer on Amlogic SoCs
 113     enum:
 114       - vpu-cvbs
 115       - vpu-hdmi
 116
 117 patternProperties:
 118   "^[a-zA-Z0-9-]+-supply$":
 119     $ref: /schemas/types.yaml#/definitions/phandle
 120     description:
 121       Regulators used by the framebuffer. These should be named
 122       according to the names in the device design.
 123
 124 required:
 125   # The binding requires also reg, width, height, stride and format,
 126   # but usually they will be filled by the bootloader.
 127   - compatible
 128
 129 allOf:
 130   - if:
 131       properties:
 132         compatible:
 133           contains:
 134             const: allwinner,simple-framebuffer
 135
 136     then:
 137       required:
 138         - allwinner,pipeline
 139
 140   - if:
 141       properties:
 142         compatible:
 143           contains:
 144             const: amlogic,simple-framebuffer
 145
 146     then:
 147       required:
 148         - amlogic,pipeline
 149
 150
 151 additionalProperties: false
 152
 153 examples:
 154   - |
 155     / {
 156         compatible = "foo";
 157         model = "foo";
 158         #address-cells = <1>;
 159         #size-cells = <1>;
 160
 161         chosen {
 162             #address-cells = <1>;
 163             #size-cells = <1>;
 164             framebuffer0: framebuffer@1d385000 {
 165                 compatible = "allwinner,simple-framebuffer", "simple-framebuffer";
 166                 allwinner,pipeline = "de_be0-lcd0";
 167                 reg = <0x1d385000 3840000>;
 168                 width = <1600>;
 169                 height = <1200>;
 170                 stride = <3200>;
 171                 format = "r5g6b5";
 172                 clocks = <&ahb_gates 36>, <&ahb_gates 43>, <&ahb_gates 44>;
 173                 lcd-supply = <&reg_dc1sw>;
 174                 display = <&lcdc0>;
 175             };
 176         };
 177     };
 178
 179 ...