include/drm/gud.h

0001 /* SPDX-License-Identifier: MIT */
0002 /*
0003  * Copyright 2020 Noralf Trønnes
0004  */
0005
0006 #ifndef __LINUX_GUD_H
0007 #define __LINUX_GUD_H
0008
0009 #include <linux/types.h>
0010
0011 /*
0012  * struct gud_display_descriptor_req - Display descriptor
0013  * @magic: Magic value GUD_DISPLAY_MAGIC
0014  * @version: Protocol version
0015  * @flags: Flags
0016  *         - STATUS_ON_SET: Always do a status request after a SET request.
0017  *                          This is used by the Linux gadget driver since it has
0018  *                          no way to control the status stage of a control OUT
0019  *                          request that has a payload.
0020  *         - FULL_UPDATE:   Always send the entire framebuffer when flushing changes.
0021  *                          The GUD_REQ_SET_BUFFER request will not be sent
0022  *                          before each bulk transfer, it will only be sent if the
0023  *                          previous bulk transfer had failed. This gives the device
0024  *                          a chance to reset its state machine if needed.
0025  *                          This flag can not be used in combination with compression.
0026  * @compression: Supported compression types
0027  *               - GUD_COMPRESSION_LZ4: LZ4 lossless compression.
0028  * @max_buffer_size: Maximum buffer size the device can handle (optional).
0029  *                   This is useful for devices that don't have a big enough
0030  *                   buffer to decompress the entire framebuffer in one go.
0031  * @min_width: Minimum pixel width the controller can handle
0032  * @max_width: Maximum width
0033  * @min_height: Minimum height
0034  * @max_height: Maximum height
0035  *
0036  * Devices that have only one display mode will have min_width == max_width
0037  * and min_height == max_height.
0038  */
0039 struct gud_display_descriptor_req {
0040     __le32 magic;
0041 #define GUD_DISPLAY_MAGIC           0x1d50614d
0042     __u8 version;
0043     __le32 flags;
0044 #define GUD_DISPLAY_FLAG_STATUS_ON_SET      BIT(0)
0045 #define GUD_DISPLAY_FLAG_FULL_UPDATE        BIT(1)
0046     __u8 compression;
0047 #define GUD_COMPRESSION_LZ4         BIT(0)
0048     __le32 max_buffer_size;
0049     __le32 min_width;
0050     __le32 max_width;
0051     __le32 min_height;
0052     __le32 max_height;
0053 } __packed;
0054
0055 /*
0056  * struct gud_property_req - Property
0057  * @prop: Property
0058  * @val: Value
0059  */
0060 struct gud_property_req {
0061     __le16 prop;
0062     __le64 val;
0063 } __packed;
0064
0065 /*
0066  * struct gud_display_mode_req - Display mode
0067  * @clock: Pixel clock in kHz
0068  * @hdisplay: Horizontal display size
0069  * @hsync_start: Horizontal sync start
0070  * @hsync_end: Horizontal sync end
0071  * @htotal: Horizontal total size
0072  * @vdisplay: Vertical display size
0073  * @vsync_start: Vertical sync start
0074  * @vsync_end: Vertical sync end
0075  * @vtotal: Vertical total size
0076  * @flags: Bits 0-13 are the same as in the RandR protocol and also what DRM uses.
0077  *         The deprecated bits are reused for internal protocol flags leaving us
0078  *         free to follow DRM for the other bits in the future.
0079  *         - FLAG_PREFERRED: Set on the preferred display mode.
0080  */
0081 struct gud_display_mode_req {
0082     __le32 clock;
0083     __le16 hdisplay;
0084     __le16 hsync_start;
0085     __le16 hsync_end;
0086     __le16 htotal;
0087     __le16 vdisplay;
0088     __le16 vsync_start;
0089     __le16 vsync_end;
0090     __le16 vtotal;
0091     __le32 flags;
0092 #define GUD_DISPLAY_MODE_FLAG_PHSYNC        BIT(0)
0093 #define GUD_DISPLAY_MODE_FLAG_NHSYNC        BIT(1)
0094 #define GUD_DISPLAY_MODE_FLAG_PVSYNC        BIT(2)
0095 #define GUD_DISPLAY_MODE_FLAG_NVSYNC        BIT(3)
0096 #define GUD_DISPLAY_MODE_FLAG_INTERLACE     BIT(4)
0097 #define GUD_DISPLAY_MODE_FLAG_DBLSCAN       BIT(5)
0098 #define GUD_DISPLAY_MODE_FLAG_CSYNC     BIT(6)
0099 #define GUD_DISPLAY_MODE_FLAG_PCSYNC        BIT(7)
0100 #define GUD_DISPLAY_MODE_FLAG_NCSYNC        BIT(8)
0101 #define GUD_DISPLAY_MODE_FLAG_HSKEW     BIT(9)
0102 /* BCast and PixelMultiplex are deprecated */
0103 #define GUD_DISPLAY_MODE_FLAG_DBLCLK        BIT(12)
0104 #define GUD_DISPLAY_MODE_FLAG_CLKDIV2       BIT(13)
0105 #define GUD_DISPLAY_MODE_FLAG_USER_MASK     \
0106         (GUD_DISPLAY_MODE_FLAG_PHSYNC | GUD_DISPLAY_MODE_FLAG_NHSYNC | \
0107         GUD_DISPLAY_MODE_FLAG_PVSYNC | GUD_DISPLAY_MODE_FLAG_NVSYNC | \
0108         GUD_DISPLAY_MODE_FLAG_INTERLACE | GUD_DISPLAY_MODE_FLAG_DBLSCAN | \
0109         GUD_DISPLAY_MODE_FLAG_CSYNC | GUD_DISPLAY_MODE_FLAG_PCSYNC | \
0110         GUD_DISPLAY_MODE_FLAG_NCSYNC | GUD_DISPLAY_MODE_FLAG_HSKEW | \
0111         GUD_DISPLAY_MODE_FLAG_DBLCLK | GUD_DISPLAY_MODE_FLAG_CLKDIV2)
0112 /* Internal protocol flags */
0113 #define GUD_DISPLAY_MODE_FLAG_PREFERRED     BIT(10)
0114 } __packed;
0115
0116 /*
0117  * struct gud_connector_descriptor_req - Connector descriptor
0118  * @connector_type: Connector type (GUD_CONNECTOR_TYPE_*).
0119  *                  If the host doesn't support the type it should fall back to PANEL.
0120  * @flags: Flags
0121  *         - POLL_STATUS: Connector status can change (polled every 10 seconds)
0122  *         - INTERLACE: Interlaced modes are supported
0123  *         - DOUBLESCAN: Doublescan modes are supported
0124  */
0125 struct gud_connector_descriptor_req {
0126     __u8 connector_type;
0127 #define GUD_CONNECTOR_TYPE_PANEL        0
0128 #define GUD_CONNECTOR_TYPE_VGA          1
0129 #define GUD_CONNECTOR_TYPE_COMPOSITE        2
0130 #define GUD_CONNECTOR_TYPE_SVIDEO       3
0131 #define GUD_CONNECTOR_TYPE_COMPONENT        4
0132 #define GUD_CONNECTOR_TYPE_DVI          5
0133 #define GUD_CONNECTOR_TYPE_DISPLAYPORT      6
0134 #define GUD_CONNECTOR_TYPE_HDMI         7
0135     __le32 flags;
0136 #define GUD_CONNECTOR_FLAGS_POLL_STATUS     BIT(0)
0137 #define GUD_CONNECTOR_FLAGS_INTERLACE       BIT(1)
0138 #define GUD_CONNECTOR_FLAGS_DOUBLESCAN      BIT(2)
0139 } __packed;
0140
0141 /*
0142  * struct gud_set_buffer_req - Set buffer transfer info
0143  * @x: X position of rectangle
0144  * @y: Y position
0145  * @width: Pixel width of rectangle
0146  * @height: Pixel height
0147  * @length: Buffer length in bytes
0148  * @compression: Transfer compression
0149  * @compressed_length: Compressed buffer length
0150  *
0151  * This request is issued right before the bulk transfer.
0152  * @x, @y, @width and @height specifies the rectangle where the buffer should be
0153  * placed inside the framebuffer.
0154  */
0155 struct gud_set_buffer_req {
0156     __le32 x;
0157     __le32 y;
0158     __le32 width;
0159     __le32 height;
0160     __le32 length;
0161     __u8 compression;
0162     __le32 compressed_length;
0163 } __packed;
0164
0165 /*
0166  * struct gud_state_req - Display state
0167  * @mode: Display mode
0168  * @format: Pixel format GUD_PIXEL_FORMAT_*
0169  * @connector: Connector index
0170  * @properties: Array of properties
0171  *
0172  * The entire state is transferred each time there's a change.
0173  */
0174 struct gud_state_req {
0175     struct gud_display_mode_req mode;
0176     __u8 format;
0177     __u8 connector;
0178     struct gud_property_req properties[];
0179 } __packed;
0180
0181 /* List of supported connector properties: */
0182
0183 /* Margins in pixels to deal with overscan, range 0-100 */
0184 #define GUD_PROPERTY_TV_LEFT_MARGIN         1
0185 #define GUD_PROPERTY_TV_RIGHT_MARGIN            2
0186 #define GUD_PROPERTY_TV_TOP_MARGIN          3
0187 #define GUD_PROPERTY_TV_BOTTOM_MARGIN           4
0188 #define GUD_PROPERTY_TV_MODE                5
0189 /* Brightness in percent, range 0-100 */
0190 #define GUD_PROPERTY_TV_BRIGHTNESS          6
0191 /* Contrast in percent, range 0-100 */
0192 #define GUD_PROPERTY_TV_CONTRAST            7
0193 /* Flicker reduction in percent, range 0-100 */
0194 #define GUD_PROPERTY_TV_FLICKER_REDUCTION       8
0195 /* Overscan in percent, range 0-100 */
0196 #define GUD_PROPERTY_TV_OVERSCAN            9
0197 /* Saturation in percent, range 0-100 */
0198 #define GUD_PROPERTY_TV_SATURATION          10
0199 /* Hue in percent, range 0-100 */
0200 #define GUD_PROPERTY_TV_HUE             11
0201
0202 /*
0203  * Backlight brightness is in the range 0-100 inclusive. The value represents the human perceptual
0204  * brightness and not a linear PWM value. 0 is minimum brightness which should not turn the
0205  * backlight completely off. The DPMS connector property should be used to control power which will
0206  * trigger a GUD_REQ_SET_DISPLAY_ENABLE request.
0207  *
0208  * This does not map to a DRM property, it is used with the backlight device.
0209  */
0210 #define GUD_PROPERTY_BACKLIGHT_BRIGHTNESS       12
0211
0212 /* List of supported properties that are not connector propeties: */
0213
0214 /*
0215  * Plane rotation. Should return the supported bitmask on
0216  * GUD_REQ_GET_PROPERTIES. GUD_ROTATION_0 is mandatory.
0217  *
0218  * Note: This is not display rotation so 90/270 will need scaling to make it fit (unless squared).
0219  */
0220 #define GUD_PROPERTY_ROTATION               50
0221   #define GUD_ROTATION_0            BIT(0)
0222   #define GUD_ROTATION_90           BIT(1)
0223   #define GUD_ROTATION_180          BIT(2)
0224   #define GUD_ROTATION_270          BIT(3)
0225   #define GUD_ROTATION_REFLECT_X        BIT(4)
0226   #define GUD_ROTATION_REFLECT_Y        BIT(5)
0227   #define GUD_ROTATION_MASK         (GUD_ROTATION_0 | GUD_ROTATION_90 | \
0228                         GUD_ROTATION_180 | GUD_ROTATION_270 | \
0229                         GUD_ROTATION_REFLECT_X | GUD_ROTATION_REFLECT_Y)
0230
0231 /* USB Control requests: */
0232
0233 /* Get status from the last GET/SET control request. Value is u8. */
0234 #define GUD_REQ_GET_STATUS              0x00
0235   /* Status values: */
0236   #define GUD_STATUS_OK             0x00
0237   #define GUD_STATUS_BUSY           0x01
0238   #define GUD_STATUS_REQUEST_NOT_SUPPORTED  0x02
0239   #define GUD_STATUS_PROTOCOL_ERROR     0x03
0240   #define GUD_STATUS_INVALID_PARAMETER      0x04
0241   #define GUD_STATUS_ERROR          0x05
0242
0243 /* Get display descriptor as a &gud_display_descriptor_req */
0244 #define GUD_REQ_GET_DESCRIPTOR              0x01
0245
0246 /* Get supported pixel formats as a byte array of GUD_PIXEL_FORMAT_* */
0247 #define GUD_REQ_GET_FORMATS             0x40
0248   #define GUD_FORMATS_MAX_NUM           32
0249   #define GUD_PIXEL_FORMAT_R1           0x01 /* 1-bit monochrome */
0250   #define GUD_PIXEL_FORMAT_R8           0x08 /* 8-bit greyscale */
0251   #define GUD_PIXEL_FORMAT_XRGB1111     0x20
0252   #define GUD_PIXEL_FORMAT_RGB332       0x30
0253   #define GUD_PIXEL_FORMAT_RGB565       0x40
0254   #define GUD_PIXEL_FORMAT_RGB888       0x50
0255   #define GUD_PIXEL_FORMAT_XRGB8888     0x80
0256   #define GUD_PIXEL_FORMAT_ARGB8888     0x81
0257
0258 /*
0259  * Get supported properties that are not connector propeties as a &gud_property_req array.
0260  * gud_property_req.val often contains the initial value for the property.
0261  */
0262 #define GUD_REQ_GET_PROPERTIES              0x41
0263   #define GUD_PROPERTIES_MAX_NUM        32
0264
0265 /* Connector requests have the connector index passed in the wValue field */
0266
0267 /* Get connector descriptors as an array of &gud_connector_descriptor_req */
0268 #define GUD_REQ_GET_CONNECTORS              0x50
0269   #define GUD_CONNECTORS_MAX_NUM        32
0270
0271 /*
0272  * Get properties supported by the connector as a &gud_property_req array.
0273  * gud_property_req.val often contains the initial value for the property.
0274  */
0275 #define GUD_REQ_GET_CONNECTOR_PROPERTIES        0x51
0276   #define GUD_CONNECTOR_PROPERTIES_MAX_NUM  32
0277
0278 /*
0279  * Issued when there's a TV_MODE property present.
0280  * Gets an array of the supported TV_MODE names each entry of length
0281  * GUD_CONNECTOR_TV_MODE_NAME_LEN. Names must be NUL-terminated.
0282  */
0283 #define GUD_REQ_GET_CONNECTOR_TV_MODE_VALUES        0x52
0284   #define GUD_CONNECTOR_TV_MODE_NAME_LEN    16
0285   #define GUD_CONNECTOR_TV_MODE_MAX_NUM     16
0286
0287 /* When userspace checks connector status, this is issued first, not used for poll requests. */
0288 #define GUD_REQ_SET_CONNECTOR_FORCE_DETECT      0x53
0289
0290 /*
0291  * Get connector status. Value is u8.
0292  *
0293  * Userspace will get a HOTPLUG uevent if one of the following is true:
0294  * - Connection status has changed since last
0295  * - CHANGED is set
0296  */
0297 #define GUD_REQ_GET_CONNECTOR_STATUS            0x54
0298   #define GUD_CONNECTOR_STATUS_DISCONNECTED 0x00
0299   #define GUD_CONNECTOR_STATUS_CONNECTED    0x01
0300   #define GUD_CONNECTOR_STATUS_UNKNOWN      0x02
0301   #define GUD_CONNECTOR_STATUS_CONNECTED_MASK   0x03
0302   #define GUD_CONNECTOR_STATUS_CHANGED      BIT(7)
0303
0304 /*
0305  * Display modes can be fetched as either EDID data or an array of &gud_display_mode_req.
0306  *
0307  * If GUD_REQ_GET_CONNECTOR_MODES returns zero, EDID is used to create display modes.
0308  * If both display modes and EDID are returned, EDID is just passed on to userspace
0309  * in the EDID connector property.
0310  */
0311
0312 /* Get &gud_display_mode_req array of supported display modes */
0313 #define GUD_REQ_GET_CONNECTOR_MODES         0x55
0314   #define GUD_CONNECTOR_MAX_NUM_MODES       128
0315
0316 /* Get Extended Display Identification Data */
0317 #define GUD_REQ_GET_CONNECTOR_EDID          0x56
0318   #define GUD_CONNECTOR_MAX_EDID_LEN        2048
0319
0320 /* Set buffer properties before bulk transfer as &gud_set_buffer_req */
0321 #define GUD_REQ_SET_BUFFER              0x60
0322
0323 /* Check display configuration as &gud_state_req */
0324 #define GUD_REQ_SET_STATE_CHECK             0x61
0325
0326 /* Apply the previous STATE_CHECK configuration */
0327 #define GUD_REQ_SET_STATE_COMMIT            0x62
0328
0329 /* Enable/disable the display controller, value is u8: 0/1 */
0330 #define GUD_REQ_SET_CONTROLLER_ENABLE           0x63
0331
0332 /* Enable/disable display/output (DPMS), value is u8: 0/1 */
0333 #define GUD_REQ_SET_DISPLAY_ENABLE          0x64
0334
0335 #endif