include/drm/gud.h

   1 /* SPDX-License-Identifier: MIT */
   2 /*
   3  * Copyright 2020 Noralf Trønnes
   4  */
   5
   6 #ifndef __LINUX_GUD_H
   7 #define __LINUX_GUD_H
   8
   9 #include <linux/types.h>
  10
  11 /*
  12  * struct gud_display_descriptor_req - Display descriptor
  13  * @magic: Magic value GUD_DISPLAY_MAGIC
  14  * @version: Protocol version
  15  * @flags: Flags
  16  *         - STATUS_ON_SET: Always do a status request after a SET request.
  17  *                          This is used by the Linux gadget driver since it has
  18  *                          no way to control the status stage of a control OUT
  19  *                          request that has a payload.
  20  *         - FULL_UPDATE:   Always send the entire framebuffer when flushing changes.
  21  *                          The GUD_REQ_SET_BUFFER request will not be sent
  22  *                          before each bulk transfer, it will only be sent if the
  23  *                          previous bulk transfer had failed. This gives the device
  24  *                          a chance to reset its state machine if needed.
  25  *                          This flag can not be used in combination with compression.
  26  * @compression: Supported compression types
  27  *               - GUD_COMPRESSION_LZ4: LZ4 lossless compression.
  28  * @max_buffer_size: Maximum buffer size the device can handle (optional).
  29  *                   This is useful for devices that don't have a big enough
  30  *                   buffer to decompress the entire framebuffer in one go.
  31  * @min_width: Minimum pixel width the controller can handle
  32  * @max_width: Maximum width
  33  * @min_height: Minimum height
  34  * @max_height: Maximum height
  35  *
  36  * Devices that have only one display mode will have min_width == max_width
  37  * and min_height == max_height.
  38  */
  39 struct gud_display_descriptor_req {
  40         __le32 magic;
  41 #define GUD_DISPLAY_MAGIC                       0x1d50614d
  42         __u8 version;
  43         __le32 flags;
  44 #define GUD_DISPLAY_FLAG_STATUS_ON_SET          BIT(0)
  45 #define GUD_DISPLAY_FLAG_FULL_UPDATE            BIT(1)
  46         __u8 compression;
  47 #define GUD_COMPRESSION_LZ4                     BIT(0)
  48         __le32 max_buffer_size;
  49         __le32 min_width;
  50         __le32 max_width;
  51         __le32 min_height;
  52         __le32 max_height;
  53 } __packed;
  54
  55 /*
  56  * struct gud_property_req - Property
  57  * @prop: Property
  58  * @val: Value
  59  */
  60 struct gud_property_req {
  61         __le16 prop;
  62         __le64 val;
  63 } __packed;
  64
  65 /*
  66  * struct gud_display_mode_req - Display mode
  67  * @clock: Pixel clock in kHz
  68  * @hdisplay: Horizontal display size
  69  * @hsync_start: Horizontal sync start
  70  * @hsync_end: Horizontal sync end
  71  * @htotal: Horizontal total size
  72  * @vdisplay: Vertical display size
  73  * @vsync_start: Vertical sync start
  74  * @vsync_end: Vertical sync end
  75  * @vtotal: Vertical total size
  76  * @flags: Bits 0-13 are the same as in the RandR protocol and also what DRM uses.
  77  *         The deprecated bits are reused for internal protocol flags leaving us
  78  *         free to follow DRM for the other bits in the future.
  79  *         - FLAG_PREFERRED: Set on the preferred display mode.
  80  */
  81 struct gud_display_mode_req {
  82         __le32 clock;
  83         __le16 hdisplay;
  84         __le16 hsync_start;
  85         __le16 hsync_end;
  86         __le16 htotal;
  87         __le16 vdisplay;
  88         __le16 vsync_start;
  89         __le16 vsync_end;
  90         __le16 vtotal;
  91         __le32 flags;
  92 #define GUD_DISPLAY_MODE_FLAG_PHSYNC            BIT(0)
  93 #define GUD_DISPLAY_MODE_FLAG_NHSYNC            BIT(1)
  94 #define GUD_DISPLAY_MODE_FLAG_PVSYNC            BIT(2)
  95 #define GUD_DISPLAY_MODE_FLAG_NVSYNC            BIT(3)
  96 #define GUD_DISPLAY_MODE_FLAG_INTERLACE         BIT(4)
  97 #define GUD_DISPLAY_MODE_FLAG_DBLSCAN           BIT(5)
  98 #define GUD_DISPLAY_MODE_FLAG_CSYNC             BIT(6)
  99 #define GUD_DISPLAY_MODE_FLAG_PCSYNC            BIT(7)
 100 #define GUD_DISPLAY_MODE_FLAG_NCSYNC            BIT(8)
 101 #define GUD_DISPLAY_MODE_FLAG_HSKEW             BIT(9)
 102 /* BCast and PixelMultiplex are deprecated */
 103 #define GUD_DISPLAY_MODE_FLAG_DBLCLK            BIT(12)
 104 #define GUD_DISPLAY_MODE_FLAG_CLKDIV2           BIT(13)
 105 #define GUD_DISPLAY_MODE_FLAG_USER_MASK         \
 106                 (GUD_DISPLAY_MODE_FLAG_PHSYNC | GUD_DISPLAY_MODE_FLAG_NHSYNC | \
 107                 GUD_DISPLAY_MODE_FLAG_PVSYNC | GUD_DISPLAY_MODE_FLAG_NVSYNC | \
 108                 GUD_DISPLAY_MODE_FLAG_INTERLACE | GUD_DISPLAY_MODE_FLAG_DBLSCAN | \
 109                 GUD_DISPLAY_MODE_FLAG_CSYNC | GUD_DISPLAY_MODE_FLAG_PCSYNC | \
 110                 GUD_DISPLAY_MODE_FLAG_NCSYNC | GUD_DISPLAY_MODE_FLAG_HSKEW | \
 111                 GUD_DISPLAY_MODE_FLAG_DBLCLK | GUD_DISPLAY_MODE_FLAG_CLKDIV2)
 112 /* Internal protocol flags */
 113 #define GUD_DISPLAY_MODE_FLAG_PREFERRED         BIT(10)
 114 } __packed;
 115
 116 /*
 117  * struct gud_connector_descriptor_req - Connector descriptor
 118  * @connector_type: Connector type (GUD_CONNECTOR_TYPE_*).
 119  *                  If the host doesn't support the type it should fall back to PANEL.
 120  * @flags: Flags
 121  *         - POLL_STATUS: Connector status can change (polled every 10 seconds)
 122  *         - INTERLACE: Interlaced modes are supported
 123  *         - DOUBLESCAN: Doublescan modes are supported
 124  */
 125 struct gud_connector_descriptor_req {
 126         __u8 connector_type;
 127 #define GUD_CONNECTOR_TYPE_PANEL                0
 128 #define GUD_CONNECTOR_TYPE_VGA                  1
 129 #define GUD_CONNECTOR_TYPE_COMPOSITE            2
 130 #define GUD_CONNECTOR_TYPE_SVIDEO               3
 131 #define GUD_CONNECTOR_TYPE_COMPONENT            4
 132 #define GUD_CONNECTOR_TYPE_DVI                  5
 133 #define GUD_CONNECTOR_TYPE_DISPLAYPORT          6
 134 #define GUD_CONNECTOR_TYPE_HDMI                 7
 135         __le32 flags;
 136 #define GUD_CONNECTOR_FLAGS_POLL_STATUS         BIT(0)
 137 #define GUD_CONNECTOR_FLAGS_INTERLACE           BIT(1)
 138 #define GUD_CONNECTOR_FLAGS_DOUBLESCAN          BIT(2)
 139 } __packed;
 140
 141 /*
 142  * struct gud_set_buffer_req - Set buffer transfer info
 143  * @x: X position of rectangle
 144  * @y: Y position
 145  * @width: Pixel width of rectangle
 146  * @height: Pixel height
 147  * @length: Buffer length in bytes
 148  * @compression: Transfer compression
 149  * @compressed_length: Compressed buffer length
 150  *
 151  * This request is issued right before the bulk transfer.
 152  * @x, @y, @width and @height specifies the rectangle where the buffer should be
 153  * placed inside the framebuffer.
 154  */
 155 struct gud_set_buffer_req {
 156         __le32 x;
 157         __le32 y;
 158         __le32 width;
 159         __le32 height;
 160         __le32 length;
 161         __u8 compression;
 162         __le32 compressed_length;
 163 } __packed;
 164
 165 /*
 166  * struct gud_state_req - Display state
 167  * @mode: Display mode
 168  * @format: Pixel format GUD_PIXEL_FORMAT_*
 169  * @connector: Connector index
 170  * @properties: Array of properties
 171  *
 172  * The entire state is transferred each time there's a change.
 173  */
 174 struct gud_state_req {
 175         struct gud_display_mode_req mode;
 176         __u8 format;
 177         __u8 connector;
 178         struct gud_property_req properties[];
 179 } __packed;
 180
 181 /* List of supported connector properties: */
 182
 183 /* Margins in pixels to deal with overscan, range 0-100 */
 184 #define GUD_PROPERTY_TV_LEFT_MARGIN                     1
 185 #define GUD_PROPERTY_TV_RIGHT_MARGIN                    2
 186 #define GUD_PROPERTY_TV_TOP_MARGIN                      3
 187 #define GUD_PROPERTY_TV_BOTTOM_MARGIN                   4
 188 #define GUD_PROPERTY_TV_MODE                            5
 189 /* Brightness in percent, range 0-100 */
 190 #define GUD_PROPERTY_TV_BRIGHTNESS                      6
 191 /* Contrast in percent, range 0-100 */
 192 #define GUD_PROPERTY_TV_CONTRAST                        7
 193 /* Flicker reduction in percent, range 0-100 */
 194 #define GUD_PROPERTY_TV_FLICKER_REDUCTION               8
 195 /* Overscan in percent, range 0-100 */
 196 #define GUD_PROPERTY_TV_OVERSCAN                        9
 197 /* Saturation in percent, range 0-100 */
 198 #define GUD_PROPERTY_TV_SATURATION                      10
 199 /* Hue in percent, range 0-100 */
 200 #define GUD_PROPERTY_TV_HUE                             11
 201
 202 /*
 203  * Backlight brightness is in the range 0-100 inclusive. The value represents the human perceptual
 204  * brightness and not a linear PWM value. 0 is minimum brightness which should not turn the
 205  * backlight completely off. The DPMS connector property should be used to control power which will
 206  * trigger a GUD_REQ_SET_DISPLAY_ENABLE request.
 207  *
 208  * This does not map to a DRM property, it is used with the backlight device.
 209  */
 210 #define GUD_PROPERTY_BACKLIGHT_BRIGHTNESS               12
 211
 212 /* List of supported properties that are not connector propeties: */
 213
 214 /*
 215  * Plane rotation. Should return the supported bitmask on
 216  * GUD_REQ_GET_PROPERTIES. GUD_ROTATION_0 is mandatory.
 217  *
 218  * Note: This is not display rotation so 90/270 will need scaling to make it fit (unless squared).
 219  */
 220 #define GUD_PROPERTY_ROTATION                           50
 221   #define GUD_ROTATION_0                        BIT(0)
 222   #define GUD_ROTATION_90                       BIT(1)
 223   #define GUD_ROTATION_180                      BIT(2)
 224   #define GUD_ROTATION_270                      BIT(3)
 225   #define GUD_ROTATION_REFLECT_X                BIT(4)
 226   #define GUD_ROTATION_REFLECT_Y                BIT(5)
 227   #define GUD_ROTATION_MASK                     (GUD_ROTATION_0 | GUD_ROTATION_90 | \
 228                                                 GUD_ROTATION_180 | GUD_ROTATION_270 | \
 229                                                 GUD_ROTATION_REFLECT_X | GUD_ROTATION_REFLECT_Y)
 230
 231 /* USB Control requests: */
 232
 233 /* Get status from the last GET/SET control request. Value is u8. */
 234 #define GUD_REQ_GET_STATUS                              0x00
 235   /* Status values: */
 236   #define GUD_STATUS_OK                         0x00
 237   #define GUD_STATUS_BUSY                       0x01
 238   #define GUD_STATUS_REQUEST_NOT_SUPPORTED      0x02
 239   #define GUD_STATUS_PROTOCOL_ERROR             0x03
 240   #define GUD_STATUS_INVALID_PARAMETER          0x04
 241   #define GUD_STATUS_ERROR                      0x05
 242
 243 /* Get display descriptor as a &gud_display_descriptor_req */
 244 #define GUD_REQ_GET_DESCRIPTOR                          0x01
 245
 246 /* Get supported pixel formats as a byte array of GUD_PIXEL_FORMAT_* */
 247 #define GUD_REQ_GET_FORMATS                             0x40
 248   #define GUD_FORMATS_MAX_NUM                   32
 249   /* R1 is a 1-bit monochrome transfer format presented to userspace as XRGB8888 */
 250   #define GUD_PIXEL_FORMAT_R1                   0x01
 251   #define GUD_PIXEL_FORMAT_XRGB1111             0x20
 252   #define GUD_PIXEL_FORMAT_RGB565               0x40
 253   #define GUD_PIXEL_FORMAT_XRGB8888             0x80
 254   #define GUD_PIXEL_FORMAT_ARGB8888             0x81
 255
 256 /*
 257  * Get supported properties that are not connector propeties as a &gud_property_req array.
 258  * gud_property_req.val often contains the initial value for the property.
 259  */
 260 #define GUD_REQ_GET_PROPERTIES                          0x41
 261   #define GUD_PROPERTIES_MAX_NUM                32
 262
 263 /* Connector requests have the connector index passed in the wValue field */
 264
 265 /* Get connector descriptors as an array of &gud_connector_descriptor_req */
 266 #define GUD_REQ_GET_CONNECTORS                          0x50
 267   #define GUD_CONNECTORS_MAX_NUM                32
 268
 269 /*
 270  * Get properties supported by the connector as a &gud_property_req array.
 271  * gud_property_req.val often contains the initial value for the property.
 272  */
 273 #define GUD_REQ_GET_CONNECTOR_PROPERTIES                0x51
 274   #define GUD_CONNECTOR_PROPERTIES_MAX_NUM      32
 275
 276 /*
 277  * Issued when there's a TV_MODE property present.
 278  * Gets an array of the supported TV_MODE names each entry of length
 279  * GUD_CONNECTOR_TV_MODE_NAME_LEN. Names must be NUL-terminated.
 280  */
 281 #define GUD_REQ_GET_CONNECTOR_TV_MODE_VALUES            0x52
 282   #define GUD_CONNECTOR_TV_MODE_NAME_LEN        16
 283   #define GUD_CONNECTOR_TV_MODE_MAX_NUM         16
 284
 285 /* When userspace checks connector status, this is issued first, not used for poll requests. */
 286 #define GUD_REQ_SET_CONNECTOR_FORCE_DETECT              0x53
 287
 288 /*
 289  * Get connector status. Value is u8.
 290  *
 291  * Userspace will get a HOTPLUG uevent if one of the following is true:
 292  * - Connection status has changed since last
 293  * - CHANGED is set
 294  */
 295 #define GUD_REQ_GET_CONNECTOR_STATUS                    0x54
 296   #define GUD_CONNECTOR_STATUS_DISCONNECTED     0x00
 297   #define GUD_CONNECTOR_STATUS_CONNECTED        0x01
 298   #define GUD_CONNECTOR_STATUS_UNKNOWN          0x02
 299   #define GUD_CONNECTOR_STATUS_CONNECTED_MASK   0x03
 300   #define GUD_CONNECTOR_STATUS_CHANGED          BIT(7)
 301
 302 /*
 303  * Display modes can be fetched as either EDID data or an array of &gud_display_mode_req.
 304  *
 305  * If GUD_REQ_GET_CONNECTOR_MODES returns zero, EDID is used to create display modes.
 306  * If both display modes and EDID are returned, EDID is just passed on to userspace
 307  * in the EDID connector property.
 308  */
 309
 310 /* Get &gud_display_mode_req array of supported display modes */
 311 #define GUD_REQ_GET_CONNECTOR_MODES                     0x55
 312   #define GUD_CONNECTOR_MAX_NUM_MODES           128
 313
 314 /* Get Extended Display Identification Data */
 315 #define GUD_REQ_GET_CONNECTOR_EDID                      0x56
 316   #define GUD_CONNECTOR_MAX_EDID_LEN            2048
 317
 318 /* Set buffer properties before bulk transfer as &gud_set_buffer_req */
 319 #define GUD_REQ_SET_BUFFER                              0x60
 320
 321 /* Check display configuration as &gud_state_req */
 322 #define GUD_REQ_SET_STATE_CHECK                         0x61
 323
 324 /* Apply the previous STATE_CHECK configuration */
 325 #define GUD_REQ_SET_STATE_COMMIT                        0x62
 326
 327 /* Enable/disable the display controller, value is u8: 0/1 */
 328 #define GUD_REQ_SET_CONTROLLER_ENABLE                   0x63
 329
 330 /* Enable/disable display/output (DPMS), value is u8: 0/1 */
 331 #define GUD_REQ_SET_DISPLAY_ENABLE                      0x64
 332
 333 #endif