| 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 |
#define GUD_PIXEL_FORMAT_R1 0x01 /* 1-bit monochrome */ |
| 250 |
#define GUD_PIXEL_FORMAT_R8 0x08 /* 8-bit greyscale */ |
| 251 |
#define GUD_PIXEL_FORMAT_XRGB1111 0x20 |
| 252 |
#define GUD_PIXEL_FORMAT_RGB332 0x30 |
| 253 |
#define GUD_PIXEL_FORMAT_RGB565 0x40 |
| 254 |
#define GUD_PIXEL_FORMAT_RGB888 0x50 |
| 255 |
#define GUD_PIXEL_FORMAT_XRGB8888 0x80 |
| 256 |
#define GUD_PIXEL_FORMAT_ARGB8888 0x81 |
| 257 |
|
| 258 |
/* |
| 259 |
* Get supported properties that are not connector propeties as a &gud_property_req array. |
| 260 |
* gud_property_req.val often contains the initial value for the property. |
| 261 |
*/ |
| 262 |
#define GUD_REQ_GET_PROPERTIES 0x41 |
| 263 |
#define GUD_PROPERTIES_MAX_NUM 32 |
| 264 |
|
| 265 |
/* Connector requests have the connector index passed in the wValue field */ |
| 266 |
|
| 267 |
/* Get connector descriptors as an array of &gud_connector_descriptor_req */ |
| 268 |
#define GUD_REQ_GET_CONNECTORS 0x50 |
| 269 |
#define GUD_CONNECTORS_MAX_NUM 32 |
| 270 |
|
| 271 |
/* |
| 272 |
* Get properties supported by the connector as a &gud_property_req array. |
| 273 |
* gud_property_req.val often contains the initial value for the property. |
| 274 |
*/ |
| 275 |
#define GUD_REQ_GET_CONNECTOR_PROPERTIES 0x51 |
| 276 |
#define GUD_CONNECTOR_PROPERTIES_MAX_NUM 32 |
| 277 |
|
| 278 |
/* |
| 279 |
* Issued when there's a TV_MODE property present. |
| 280 |
* Gets an array of the supported TV_MODE names each entry of length |
| 281 |
* GUD_CONNECTOR_TV_MODE_NAME_LEN. Names must be NUL-terminated. |
| 282 |
*/ |
| 283 |
#define GUD_REQ_GET_CONNECTOR_TV_MODE_VALUES 0x52 |
| 284 |
#define GUD_CONNECTOR_TV_MODE_NAME_LEN 16 |
| 285 |
#define GUD_CONNECTOR_TV_MODE_MAX_NUM 16 |
| 286 |
|
| 287 |
/* When userspace checks connector status, this is issued first, not used for poll requests. */ |
| 288 |
#define GUD_REQ_SET_CONNECTOR_FORCE_DETECT 0x53 |
| 289 |
|
| 290 |
/* |
| 291 |
* Get connector status. Value is u8. |
| 292 |
* |
| 293 |
* Userspace will get a HOTPLUG uevent if one of the following is true: |
| 294 |
* - Connection status has changed since last |
| 295 |
* - CHANGED is set |
| 296 |
*/ |
| 297 |
#define GUD_REQ_GET_CONNECTOR_STATUS 0x54 |
| 298 |
#define GUD_CONNECTOR_STATUS_DISCONNECTED 0x00 |
| 299 |
#define GUD_CONNECTOR_STATUS_CONNECTED 0x01 |
| 300 |
#define GUD_CONNECTOR_STATUS_UNKNOWN 0x02 |
| 301 |
#define GUD_CONNECTOR_STATUS_CONNECTED_MASK 0x03 |
| 302 |
#define GUD_CONNECTOR_STATUS_CHANGED BIT(7) |
| 303 |
|
| 304 |
/* |
| 305 |
* Display modes can be fetched as either EDID data or an array of &gud_display_mode_req. |
| 306 |
* |
| 307 |
* If GUD_REQ_GET_CONNECTOR_MODES returns zero, EDID is used to create display modes. |
| 308 |
* If both display modes and EDID are returned, EDID is just passed on to userspace |
| 309 |
* in the EDID connector property. |
| 310 |
*/ |
| 311 |
|
| 312 |
/* Get &gud_display_mode_req array of supported display modes */ |
| 313 |
#define GUD_REQ_GET_CONNECTOR_MODES 0x55 |
| 314 |
#define GUD_CONNECTOR_MAX_NUM_MODES 128 |
| 315 |
|
| 316 |
/* Get Extended Display Identification Data */ |
| 317 |
#define GUD_REQ_GET_CONNECTOR_EDID 0x56 |
| 318 |
#define GUD_CONNECTOR_MAX_EDID_LEN 2048 |
| 319 |
|
| 320 |
/* Set buffer properties before bulk transfer as &gud_set_buffer_req */ |
| 321 |
#define GUD_REQ_SET_BUFFER 0x60 |
| 322 |
|
| 323 |
/* Check display configuration as &gud_state_req */ |
| 324 |
#define GUD_REQ_SET_STATE_CHECK 0x61 |
| 325 |
|
| 326 |
/* Apply the previous STATE_CHECK configuration */ |
| 327 |
#define GUD_REQ_SET_STATE_COMMIT 0x62 |
| 328 |
|
| 329 |
/* Enable/disable the display controller, value is u8: 0/1 */ |
| 330 |
#define GUD_REQ_SET_CONTROLLER_ENABLE 0x63 |
| 331 |
|
| 332 |
/* Enable/disable display/output (DPMS), value is u8: 0/1 */ |
| 333 |
#define GUD_REQ_SET_DISPLAY_ENABLE 0x64 |
| 334 |
|
| 335 |
#endif |