336 lines · c
1/* SPDX-License-Identifier: MIT */2/*3 * Copyright 2020 Noralf Trønnes4 */5 6#ifndef __LINUX_GUD_H7#define __LINUX_GUD_H8 9#include <linux/types.h>10 11/*12 * struct gud_display_descriptor_req - Display descriptor13 * @magic: Magic value GUD_DISPLAY_MAGIC14 * @version: Protocol version15 * @flags: Flags16 * - STATUS_ON_SET: Always do a status request after a SET request.17 * This is used by the Linux gadget driver since it has18 * no way to control the status stage of a control OUT19 * 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 sent22 * before each bulk transfer, it will only be sent if the23 * previous bulk transfer had failed. This gives the device24 * a chance to reset its state machine if needed.25 * This flag can not be used in combination with compression.26 * @compression: Supported compression types27 * - 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 enough30 * buffer to decompress the entire framebuffer in one go.31 * @min_width: Minimum pixel width the controller can handle32 * @max_width: Maximum width33 * @min_height: Minimum height34 * @max_height: Maximum height35 *36 * Devices that have only one display mode will have min_width == max_width37 * and min_height == max_height.38 */39struct gud_display_descriptor_req {40 __le32 magic;41#define GUD_DISPLAY_MAGIC 0x1d50614d42 __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 - Property57 * @prop: Property58 * @val: Value59 */60struct gud_property_req {61 __le16 prop;62 __le64 val;63} __packed;64 65/*66 * struct gud_display_mode_req - Display mode67 * @clock: Pixel clock in kHz68 * @hdisplay: Horizontal display size69 * @hsync_start: Horizontal sync start70 * @hsync_end: Horizontal sync end71 * @htotal: Horizontal total size72 * @vdisplay: Vertical display size73 * @vsync_start: Vertical sync start74 * @vsync_end: Vertical sync end75 * @vtotal: Vertical total size76 * @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 us78 * free to follow DRM for the other bits in the future.79 * - FLAG_PREFERRED: Set on the preferred display mode.80 */81struct 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 descriptor118 * @connector_type: Connector type (GUD_CONNECTOR_TYPE_*).119 * If the host doesn't support the type it should fall back to PANEL.120 * @flags: Flags121 * - POLL_STATUS: Connector status can change (polled every 10 seconds)122 * - INTERLACE: Interlaced modes are supported123 * - DOUBLESCAN: Doublescan modes are supported124 */125struct gud_connector_descriptor_req {126 __u8 connector_type;127#define GUD_CONNECTOR_TYPE_PANEL 0128#define GUD_CONNECTOR_TYPE_VGA 1129#define GUD_CONNECTOR_TYPE_COMPOSITE 2130#define GUD_CONNECTOR_TYPE_SVIDEO 3131#define GUD_CONNECTOR_TYPE_COMPONENT 4132#define GUD_CONNECTOR_TYPE_DVI 5133#define GUD_CONNECTOR_TYPE_DISPLAYPORT 6134#define GUD_CONNECTOR_TYPE_HDMI 7135 __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 info143 * @x: X position of rectangle144 * @y: Y position145 * @width: Pixel width of rectangle146 * @height: Pixel height147 * @length: Buffer length in bytes148 * @compression: Transfer compression149 * @compressed_length: Compressed buffer length150 *151 * This request is issued right before the bulk transfer.152 * @x, @y, @width and @height specifies the rectangle where the buffer should be153 * placed inside the framebuffer.154 */155struct 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 state167 * @mode: Display mode168 * @format: Pixel format GUD_PIXEL_FORMAT_*169 * @connector: Connector index170 * @properties: Array of properties171 *172 * The entire state is transferred each time there's a change.173 */174struct 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 1185#define GUD_PROPERTY_TV_RIGHT_MARGIN 2186#define GUD_PROPERTY_TV_TOP_MARGIN 3187#define GUD_PROPERTY_TV_BOTTOM_MARGIN 4188#define GUD_PROPERTY_TV_MODE 5189/* Brightness in percent, range 0-100 */190#define GUD_PROPERTY_TV_BRIGHTNESS 6191/* Contrast in percent, range 0-100 */192#define GUD_PROPERTY_TV_CONTRAST 7193/* Flicker reduction in percent, range 0-100 */194#define GUD_PROPERTY_TV_FLICKER_REDUCTION 8195/* Overscan in percent, range 0-100 */196#define GUD_PROPERTY_TV_OVERSCAN 9197/* Saturation in percent, range 0-100 */198#define GUD_PROPERTY_TV_SATURATION 10199/* Hue in percent, range 0-100 */200#define GUD_PROPERTY_TV_HUE 11201 202/*203 * Backlight brightness is in the range 0-100 inclusive. The value represents the human perceptual204 * brightness and not a linear PWM value. 0 is minimum brightness which should not turn the205 * backlight completely off. The DPMS connector property should be used to control power which will206 * 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 12211 212/* List of supported properties that are not connector propeties: */213 214/*215 * Plane rotation. Should return the supported bitmask on216 * 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 50221 #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 0x00235 /* Status values: */236 #define GUD_STATUS_OK 0x00237 #define GUD_STATUS_BUSY 0x01238 #define GUD_STATUS_REQUEST_NOT_SUPPORTED 0x02239 #define GUD_STATUS_PROTOCOL_ERROR 0x03240 #define GUD_STATUS_INVALID_PARAMETER 0x04241 #define GUD_STATUS_ERROR 0x05242 243/* Get display descriptor as a &gud_display_descriptor_req */244#define GUD_REQ_GET_DESCRIPTOR 0x01245 246/* Get supported pixel formats as a byte array of GUD_PIXEL_FORMAT_* */247#define GUD_REQ_GET_FORMATS 0x40248 #define GUD_FORMATS_MAX_NUM 32249 #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 0x20252 #define GUD_PIXEL_FORMAT_RGB332 0x30253 #define GUD_PIXEL_FORMAT_RGB565 0x40254 #define GUD_PIXEL_FORMAT_RGB888 0x50255 #define GUD_PIXEL_FORMAT_XRGB8888 0x80256 #define GUD_PIXEL_FORMAT_ARGB8888 0x81257 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 0x41263 #define GUD_PROPERTIES_MAX_NUM 32264 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 0x50269 #define GUD_CONNECTORS_MAX_NUM 32270 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 0x51276 #define GUD_CONNECTOR_PROPERTIES_MAX_NUM 32277 278/*279 * Issued when there's a TV_MODE property present.280 * Gets an array of the supported TV_MODE names each entry of length281 * GUD_CONNECTOR_TV_MODE_NAME_LEN. Names must be NUL-terminated.282 */283#define GUD_REQ_GET_CONNECTOR_TV_MODE_VALUES 0x52284 #define GUD_CONNECTOR_TV_MODE_NAME_LEN 16285 #define GUD_CONNECTOR_TV_MODE_MAX_NUM 16286 287/* When userspace checks connector status, this is issued first, not used for poll requests. */288#define GUD_REQ_SET_CONNECTOR_FORCE_DETECT 0x53289 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 last295 * - CHANGED is set296 */297#define GUD_REQ_GET_CONNECTOR_STATUS 0x54298 #define GUD_CONNECTOR_STATUS_DISCONNECTED 0x00299 #define GUD_CONNECTOR_STATUS_CONNECTED 0x01300 #define GUD_CONNECTOR_STATUS_UNKNOWN 0x02301 #define GUD_CONNECTOR_STATUS_CONNECTED_MASK 0x03302 #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 userspace309 * 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 0x55314 #define GUD_CONNECTOR_MAX_NUM_MODES 128315 316/* Get Extended Display Identification Data */317#define GUD_REQ_GET_CONNECTOR_EDID 0x56318 #define GUD_CONNECTOR_MAX_EDID_LEN 2048319 320/* Set buffer properties before bulk transfer as &gud_set_buffer_req */321#define GUD_REQ_SET_BUFFER 0x60322 323/* Check display configuration as &gud_state_req */324#define GUD_REQ_SET_STATE_CHECK 0x61325 326/* Apply the previous STATE_CHECK configuration */327#define GUD_REQ_SET_STATE_COMMIT 0x62328 329/* Enable/disable the display controller, value is u8: 0/1 */330#define GUD_REQ_SET_CONTROLLER_ENABLE 0x63331 332/* Enable/disable display/output (DPMS), value is u8: 0/1 */333#define GUD_REQ_SET_DISPLAY_ENABLE 0x64334 335#endif336