~emersion/drmdb

5046ca990b3604ebf4a535753d0da6b151f37645 — Simon Ser 21 days ago 34c9772 master
drmdoc: sort props by name

This ensures the output order is deterministic.
M drmdoc/color-management-properties.go => drmdoc/color-management-properties.go +2 -2
@@ 3,9 3,9 @@
package drmdoc

var colorManagementProperties = map[string]string{
	"DEGAMMA_LUT_SIZE": "Unsinged range property to give the size of the lookup table to be set\non the DEGAMMA_LUT property (the size depends on the underlying\nhardware). If drivers support multiple LUT sizes then they should\npublish the largest size, and sub-sample smaller sized LUTs (e.g. for\nsplit-gamma modes) appropriately.",
	"CTM":              "Blob property to set the current transformation matrix (CTM) apply to\npixel data after the lookup through the degamma LUT and before the\nlookup through the gamma LUT. The data is interpreted as a struct\n&drm_color_ctm.\n\nSetting this to NULL (blob property value set to 0) means a\nunit/pass-thru matrix should be used. This is generally the driver\nboot-up state too. Drivers can access the blob for the color conversion\nmatrix through &drm_crtc_state.ctm.",
	"DEGAMMA_LUT":      "Blob property to set the degamma lookup table (LUT) mapping pixel data\nfrom the framebuffer before it is given to the transformation matrix.\nThe data is interpreted as an array of &struct drm_color_lut elements.\nHardware might choose not to use the full precision of the LUT elements\nnor use all the elements of the LUT (for example the hardware might\nchoose to interpolate between LUT[0] and LUT[4]).\n\nSetting this to NULL (blob property value set to 0) means a\nlinear/pass-thru gamma table should be used. This is generally the\ndriver boot-up state too. Drivers can access this blob through\n&drm_crtc_state.degamma_lut.",
	"DEGAMMA_LUT_SIZE": "Unsinged range property to give the size of the lookup table to be set\non the DEGAMMA_LUT property (the size depends on the underlying\nhardware). If drivers support multiple LUT sizes then they should\npublish the largest size, and sub-sample smaller sized LUTs (e.g. for\nsplit-gamma modes) appropriately.",
	"GAMMA_LUT":        "Blob property to set the gamma lookup table (LUT) mapping pixel data\nafter the transformation matrix to data sent to the connector. The\ndata is interpreted as an array of &struct drm_color_lut elements.\nHardware might choose not to use the full precision of the LUT elements\nnor use all the elements of the LUT (for example the hardware might\nchoose to interpolate between LUT[0] and LUT[4]).\n\nSetting this to NULL (blob property value set to 0) means a\nlinear/pass-thru gamma table should be used. This is generally the\ndriver boot-up state too. Drivers can access this blob through\n&drm_crtc_state.gamma_lut.",
	"GAMMA_LUT_SIZE":   "Unsigned range property to give the size of the lookup table to be set\non the GAMMA_LUT property (the size depends on the underlying hardware).\nIf drivers support multiple LUT sizes then they should publish the\nlargest size, and sub-sample smaller sized LUTs (e.g. for split-gamma\nmodes) appropriately.\n\nThere is also support for a legacy gamma table, which is set up by calling\ndrm_mode_crtc_set_gamma_size(). Drivers which support both should use\ndrm_atomic_helper_legacy_gamma_set() to alias the legacy gamma ramp with the\n\"GAMMA_LUT\" property above.\n\nSupport for different non RGB color encodings is controlled through\n&drm_plane specific COLOR_ENCODING and COLOR_RANGE properties. They\nare set up by calling drm_plane_create_color_properties().\n\n\"COLOR_ENCODING\"\nOptional plane enum property to support different non RGB\ncolor encodings. The driver can provide a subset of standard\nenum values supported by the DRM plane.\n\n\"COLOR_RANGE\"\nOptional plane enum property to support different non RGB\ncolor parameter ranges. The driver can provide a subset of\nstandard enum values supported by the DRM plane.",
	"DEGAMMA_LUT":      "Blob property to set the degamma lookup table (LUT) mapping pixel data\nfrom the framebuffer before it is given to the transformation matrix.\nThe data is interpreted as an array of &struct drm_color_lut elements.\nHardware might choose not to use the full precision of the LUT elements\nnor use all the elements of the LUT (for example the hardware might\nchoose to interpolate between LUT[0] and LUT[4]).\n\nSetting this to NULL (blob property value set to 0) means a\nlinear/pass-thru gamma table should be used. This is generally the\ndriver boot-up state too. Drivers can access this blob through\n&drm_crtc_state.degamma_lut.",
}

M drmdoc/generate.go => drmdoc/generate.go +10 -2
@@ 6,10 6,11 @@ import (
	"bufio"
	"bytes"
	"fmt"
	"go/format"
	"log"
	"net/http"
	"go/format"
	"os"
	"sort"
	"strings"
	"unicode"
)


@@ 150,7 151,14 @@ package drmdoc
var ` + symbol + ` = map[string]string{
`)

	for name, desc := range props {
	propNames := make([]string, 0, len(props))
	for name := range props {
		propNames = append(propNames, name)
	}
	sort.Strings(propNames)

	for _, name := range propNames {
		desc := props[name]
		fmt.Fprintf(&out, "\t%q: %q,\n", name, desc)
	}


M drmdoc/plane-blending-properties.go => drmdoc/plane-blending-properties.go +10 -10
@@ 3,19 3,19 @@
package drmdoc

var planeBlendingProperties = map[string]string{
	"CRTC_H":           "Height for the destination rectangle. CRTC_Y plus CRTC_H can extend past\nthe currently visible vertical area of the &drm_crtc.",
	"CRTC_ID":          "Mode object ID of the &drm_crtc this plane should be connected to.\n\nNote that the source rectangle must fully lie within the bounds of the\n&drm_framebuffer. The destination rectangle can lie outside of the visible\narea of the current mode of the CRTC. It must be apprpriately clipped by the\ndriver, which can be done by calling drm_plane_helper_check_update(). Drivers\nare also allowed to round the subpixel sampling positions appropriately, but\nonly to the next full pixel. No pixel outside of the source rectangle may\never be sampled, which is important when applying more sophisticated\nfiltering than just a bilinear one when scaling. The filtering mode when\nscaling is unspecified.\n\nOn top of this basic transformation additional properties can be exposed by",
	"CRTC_W":           "Width for the destination rectangle. CRTC_X plus CRTC_W can extend past\nthe currently visible horizontal area of the &drm_crtc.",
	"CRTC_X":           "X coordinate offset for the destination rectangle. Can be negative.",
	"CRTC_Y":           "Y coordinate offset for the destination rectangle. Can be negative.",
	"FB_ID":            "Mode object ID of the &drm_framebuffer this plane should scan out.",
	"IN_FORMATS":       "Blob property which contains the set of buffer format and modifier\npairs supported by this plane. The blob is a drm_format_modifier_blob\nstruct. Without this property the plane doesn't support buffers with\nmodifiers. Userspace cannot change this property.\n\nNote that all the property extensions described here apply either to the\nplane or the CRTC (e.g. for the background color, which currently is not\nexposed and assumed to be black).",
	"SRC_H":            "Height for the source rectangle within the &drm_framebuffer, in 16.16\nfixed point. SRC_Y plus SRC_H must be within the height of the source\nframebuffer. Must be positive.",
	"SRC_W":            "Width for the source rectangle within the &drm_framebuffer, in 16.16\nfixed point. SRC_X plus SRC_W must be within the width of the source\nframebuffer. Must be positive.",
	"SRC_X":            "X coordinate offset for the source rectangle within the\n&drm_framebuffer, in 16.16 fixed point. Must be positive.",
	"SRC_Y":            "Y coordinate offset for the source rectangle within the\n&drm_framebuffer, in 16.16 fixed point. Must be positive.",
	"alpha":            "Alpha is setup with drm_plane_create_alpha_property(). It controls the\nplane-wide opacity, from transparent (0) to opaque (0xffff). It can be\ncombined with pixel alpha.\nThe pixel values in the framebuffers are expected to not be\npre-multiplied by the global alpha associated to the plane.",
	"rotation":         "Rotation is set up with drm_plane_create_rotation_property(). It adds a\nrotation and reflection step between the source and destination rectangles.\nWithout this property the rectangle is only scaled, but not rotated or\nreflected.\n\nPossbile values:\n\n\"rotate-<degrees>\":\n\tSignals that a drm plane is rotated <degrees> degrees in counter\n\tclockwise direction.\n\n\"reflect-<axis>\":\n\tSignals that the contents of a drm plane is reflected along the\n\t<axis> axis, in the same way as mirroring.\n\nreflect-x::\n\n\t\t|o |    | o|\n\t\t|  | -> |  |\n\t\t| v|    |v |\n\nreflect-y::\n\n\t\t|o |    | ^|\n\t\t|  | -> |  |\n\t\t| v|    |o |",
	"CRTC_X":           "X coordinate offset for the destination rectangle. Can be negative.",
	"pixel blend mode": "Pixel blend mode is set up with drm_plane_create_blend_mode_property().\nIt adds a blend mode for alpha blending equation selection, describing\nhow the pixels from the current plane are composited with the\nbackground.\n\n Three alpha blending equations are defined:\n\n \"None\":\n\t Blend formula that ignores the pixel alpha::\n\n\t\t out.rgb = plane_alpha * fg.rgb +\n\t\t\t (1 - plane_alpha) * bg.rgb\n\n \"Pre-multiplied\":\n\t Blend formula that assumes the pixel color values\n\t have been already pre-multiplied with the alpha\n\t channel values::\n\n\t\t out.rgb = plane_alpha * fg.rgb +\n\t\t\t (1 - (plane_alpha * fg.alpha)) * bg.rgb\n\n \"Coverage\":\n\t Blend formula that assumes the pixel color values have not\n\t been pre-multiplied and will do so when blending them to the\n\t background color values::\n\n\t\t out.rgb = plane_alpha * fg.alpha * fg.rgb +\n\t\t\t (1 - (plane_alpha * fg.alpha)) * bg.rgb\n\n Using the following symbols:\n\n \"fg.rgb\":\n\t Each of the RGB component values from the plane's pixel\n \"fg.alpha\":\n\t Alpha component value from the plane's pixel. If the plane's\n\t pixel format has no alpha component, then this is assumed to be\n\t 1.0. In these cases, this property has no effect, as all three\n\t equations become equivalent.\n \"bg.rgb\":\n\t Each of the RGB component values from the background\n \"plane_alpha\":\n\t Plane alpha value set by the plane \"alpha\" property. If the\n\t plane does not expose the \"alpha\" property, then this is\n\t assumed to be 1.0",
	"SRC_Y":            "Y coordinate offset for the source rectangle within the\n&drm_framebuffer, in 16.16 fixed point. Must be positive.",
	"SRC_W":            "Width for the source rectangle within the &drm_framebuffer, in 16.16\nfixed point. SRC_X plus SRC_W must be within the width of the source\nframebuffer. Must be positive.",
	"SRC_H":            "Height for the source rectangle within the &drm_framebuffer, in 16.16\nfixed point. SRC_Y plus SRC_H must be within the height of the source\nframebuffer. Must be positive.",
	"CRTC_W":           "Width for the destination rectangle. CRTC_X plus CRTC_W can extend past\nthe currently visible horizontal area of the &drm_crtc.",
	"CRTC_ID":          "Mode object ID of the &drm_crtc this plane should be connected to.\n\nNote that the source rectangle must fully lie within the bounds of the\n&drm_framebuffer. The destination rectangle can lie outside of the visible\narea of the current mode of the CRTC. It must be apprpriately clipped by the\ndriver, which can be done by calling drm_plane_helper_check_update(). Drivers\nare also allowed to round the subpixel sampling positions appropriately, but\nonly to the next full pixel. No pixel outside of the source rectangle may\never be sampled, which is important when applying more sophisticated\nfiltering than just a bilinear one when scaling. The filtering mode when\nscaling is unspecified.\n\nOn top of this basic transformation additional properties can be exposed by",
	"rotation":         "Rotation is set up with drm_plane_create_rotation_property(). It adds a\nrotation and reflection step between the source and destination rectangles.\nWithout this property the rectangle is only scaled, but not rotated or\nreflected.\n\nPossbile values:\n\n\"rotate-<degrees>\":\n\tSignals that a drm plane is rotated <degrees> degrees in counter\n\tclockwise direction.\n\n\"reflect-<axis>\":\n\tSignals that the contents of a drm plane is reflected along the\n\t<axis> axis, in the same way as mirroring.\n\nreflect-x::\n\n\t\t|o |    | o|\n\t\t|  | -> |  |\n\t\t| v|    |v |\n\nreflect-y::\n\n\t\t|o |    | ^|\n\t\t|  | -> |  |\n\t\t| v|    |o |",
	"zpos":             "Z position is set up with drm_plane_create_zpos_immutable_property() and\ndrm_plane_create_zpos_property(). It controls the visibility of overlapping\nplanes. Without this property the primary plane is always below the cursor\nplane, and ordering between all other planes is undefined. The positive\nZ axis points towards the user, i.e. planes with lower Z position values\nare underneath planes with higher Z position values. Two planes with the\nsame Z position value have undefined ordering. Note that the Z position\nvalue can also be immutable, to inform userspace about the hard-coded\nstacking of planes, see drm_plane_create_zpos_immutable_property(). If\nany plane has a zpos property (either mutable or immutable), then all\nplanes shall have a zpos property.",
	"CRTC_Y":           "Y coordinate offset for the destination rectangle. Can be negative.",
	"CRTC_H":           "Height for the destination rectangle. CRTC_Y plus CRTC_H can extend past\nthe currently visible vertical area of the &drm_crtc.",
	"FB_ID":            "Mode object ID of the &drm_framebuffer this plane should scan out.",
}

M drmdoc/standard-connector-properties.go => drmdoc/standard-connector-properties.go +9 -9
@@ 4,17 4,17 @@ package drmdoc

var standardConnectorProperties = map[string]string{
	"CRTC_ID":             "Mode object ID of the &drm_crtc this connector should be connected to.",
	"panel orientation":   "On some devices the LCD panel is mounted in the casing in such a way\nthat the up/top side of the panel does not match with the top side of\nthe device. Userspace can use this property to check for this.\nNote that input coordinates from touchscreens (input devices with\nINPUT_PROP_DIRECT) will still map 1:1 to the actual LCD panel\ncoordinates, so if userspace rotates the picture to adjust for\nthe orientation it must also apply the same transformation to the\ntouchscreen input coordinates. This property is initialized by calling\ndrm_connector_set_panel_orientation() or\ndrm_connector_set_panel_orientation_with_quirk()",
	"scaling mode":        "This property defines how a non-native mode is upscaled to the native\nmode of an LCD panel:\n\nNone:\n\tNo upscaling happens, scaling is left to the panel. Not all\n\tdrivers expose this mode.\nFull:\n\tThe output is upscaled to the full resolution of the panel,\n\tignoring the aspect ratio.\nCenter:\n\tNo upscaling happens, the output is centered within the native\n\tresolution the panel.\nFull aspect:\n\tThe output is upscaled to maximize either the width or height\n\twhile retaining the aspect ratio.\n\nThis property should be set up by calling\ndrm_connector_attach_scaling_mode_property(). Note that drivers\ncan also expose this property to external outputs, in which case they\nmust support \"None\", which should be the default (since external screens\nhave a built-in scaler).",
	"TILE":                "Connector tile group property to indicate how a set of DRM connector\ncompose together into one logical screen. This is used by both high-res\nexternal screens (often only using a single cable, but exposing multiple\nDP MST sinks), or high-res integrated panels (like dual-link DSI) which\nare not gen-locked. Note that for tiled panels which are genlocked, like\ndual-link LVDS or dual-link DSI, the driver should try to not expose the\ntiling and virtualise both &drm_crtc and &drm_plane if needed. Drivers\nshould update this value using drm_connector_set_tile_property().\nUserspace cannot change this property.",
	"non_desktop":         "Indicates the output should be ignored for purposes of displaying a\nstandard desktop environment or console. This is most likely because\nthe output device is not rectilinear.",
	"link-status":         "Connector link-status property to indicate the status of link. The\ndefault value of link-status is \"GOOD\". If something fails during or\nafter modeset, the kernel driver may set this to \"BAD\" and issue a\nhotplug uevent. Drivers should update this value using\ndrm_connector_set_link_status_property().\n\nWhen user-space receives the hotplug uevent and detects a \"BAD\"\nlink-status, the sink doesn't receive pixels anymore (e.g. the screen\nbecomes completely black). The list of available modes may have\nchanged. User-space is expected to pick a new mode if the current one\nhas disappeared and perform a new modeset with link-status set to\n\"GOOD\" to re-enable the connector.\n\nIf multiple connectors share the same CRTC and one of them gets a \"BAD\"\nlink-status, the other are unaffected (ie. the sinks still continue to\nreceive pixels).\n\nWhen user-space performs an atomic commit on a connector with a \"BAD\"\nlink-status without resetting the property to \"GOOD\", the sink may\nstill not receive pixels. When user-space performs an atomic commit\nwhich resets the link-status property to \"GOOD\" without the\nALLOW_MODESET flag set, it might fail because a modeset is required.\n\nUser-space can only change link-status to \"GOOD\", changing it to \"BAD\"\nis a no-op.\n\nFor backwards compatibility with non-atomic userspace the kernel\ntries to automatically set the link-status back to \"GOOD\" in the\nSETCRTC IOCTL. This might fail if the mode is no longer valid, similar\nto how it might fail if a different screen has been connected in the\ninterim.",
	"EDID":                "Blob property which contains the current EDID read from the sink. This\nis useful to parse sink identification information like vendor, model\nand serial. Drivers should update this property by calling\ndrm_connector_update_edid_property(), usually after having parsed\nthe EDID using drm_add_edid_modes(). Userspace cannot change this\nproperty.",
	"Content Protection":  "This property is used by userspace to request the kernel protect future\ncontent communicated over the link. When requested, kernel will apply\nthe appropriate means of protection (most often HDCP), and use the\nproperty to tell userspace the protection is active.\n\nDrivers can set this up by calling\ndrm_connector_attach_content_protection_property() on initialization.\n\nThe value of this property can be one of the following:\n\nDRM_MODE_CONTENT_PROTECTION_UNDESIRED = 0\n\tThe link is not protected, content is transmitted in the clear.\nDRM_MODE_CONTENT_PROTECTION_DESIRED = 1\n\tUserspace has requested content protection, but the link is not\n\tcurrently protected. When in this state, kernel should enable\n\tContent Protection as soon as possible.\nDRM_MODE_CONTENT_PROTECTION_ENABLED = 2\n\tUserspace has requested content protection, and the link is\n\tprotected. Only the driver can set the property to this value.\n\tIf userspace attempts to set to ENABLED, kernel will return\n\t-EINVAL.\n\nA few guidelines:\n\n- DESIRED state should be preserved until userspace de-asserts it by\n  setting the property to UNDESIRED. This means ENABLED should only\n  transition to UNDESIRED when the user explicitly requests it.\n- If the state is DESIRED, kernel should attempt to re-authenticate the\n  link whenever possible. This includes across disable/enable, dpms,\n  hotplug, downstream device changes, link status failures, etc..\n- Kernel sends uevent with the connector id and property id through\n  @drm_hdcp_update_content_protection, upon below kernel triggered\n  scenarios:\n\n\t- DESIRED -> ENABLED (authentication success)\n\t- ENABLED -> DESIRED (termination of authentication)\n- Please note no uevents for userspace triggered property state changes,\n  which can't fail such as\n\n\t- DESIRED/ENABLED -> UNDESIRED\n\t- UNDESIRED -> DESIRED\n- Userspace is responsible for polling the property or listen to uevents\n  to determine when the value transitions from ENABLED to DESIRED.\n  This signifies the link is no longer protected and userspace should\n  take appropriate action (whatever that might be).",
	"DPMS":                "Legacy property for setting the power state of the connector. For atomic\ndrivers this is only provided for backwards compatibility with existing\ndrivers, it remaps to controlling the \"ACTIVE\" property on the CRTC the\nconnector is linked to. Drivers should never set this property directly,\nit is handled by the DRM core by calling the &drm_connector_funcs.dpms\ncallback. For atomic drivers the remapping to the \"ACTIVE\" property is\nimplemented in the DRM core.\n\nNote that this property cannot be set through the MODE_ATOMIC ioctl,\nuserspace must use \"ACTIVE\" on the CRTC instead.\n\nWARNING:\n\nFor userspace also running on legacy drivers the \"DPMS\" semantics are a\nlot more complicated. First, userspace cannot rely on the \"DPMS\" value\nreturned by the GETCONNECTOR actually reflecting reality, because many\ndrivers fail to update it. For atomic drivers this is taken care of in\ndrm_atomic_helper_update_legacy_modeset_state().\n\nThe second issue is that the DPMS state is only well-defined when the\nconnector is connected to a CRTC. In atomic the DRM core enforces that\n\"ACTIVE\" is off in such a case, no such checks exists for \"DPMS\".\n\nFinally, when enabling an output using the legacy SETCONFIG ioctl then\n\"DPMS\" is forced to ON. But see above, that might not be reflected in\nthe software value on legacy drivers.\n\nSummarizing: Only set \"DPMS\" when the connector is known to be enabled,\nassume that a successful SETCONFIG call also sets \"DPMS\" to on, and\nnever read back the value of \"DPMS\" because it can be incorrect.",
	"HDR_OUTPUT_METADATA": "Connector property to enable userspace to send HDR Metadata to\ndriver. This metadata is based on the composition and blending\npolicies decided by user, taking into account the hardware and\nsink capabilities. The driver gets this metadata and creates a\nDynamic Range and Mastering Infoframe (DRM) in case of HDMI,\nSDP packet (Non-audio INFOFRAME SDP v1.3) for DP. This is then\nsent to sink. This notifies the sink of the upcoming frame's Color\nEncoding and Luminance parameters.\n\nUserspace first need to detect the HDR capabilities of sink by\nreading and parsing the EDID. Details of HDR metadata for HDMI\nare added in CTA 861.G spec. For DP , its defined in VESA DP\nStandard v1.4. It needs to then get the metadata information\nof the video/game/app content which are encoded in HDR (basically\nusing HDR transfer functions). With this information it needs to\ndecide on a blending policy and compose the relevant\nlayers/overlays into a common format. Once this blending is done,\nuserspace will be aware of the metadata of the composed frame to\nbe send to sink. It then uses this property to communicate this\nmetadata to driver which then make a Infoframe packet and sends\nto sink based on the type of encoder connected.\n\nUserspace will be responsible to do Tone mapping operation in case:\n\t- Some layers are HDR and others are SDR\n\t- HDR layers luminance is not same as sink\n\nIt will even need to do colorspace conversion and get all layers\nto one common colorspace for blending. It can use either GL, Media\nor display engine to get this done based on the capabilities of the\nassociated hardware.\n\nDriver expects metadata to be put in &struct hdr_output_metadata\nstructure from userspace. This is received as blob and stored in\n&drm_connector_state.hdr_output_metadata. It parses EDID and saves the\nsink metadata in &struct hdr_sink_metadata, as\n&drm_connector.hdr_sink_metadata.  Driver uses\ndrm_hdmi_infoframe_set_hdr_metadata() helper to set the HDR metadata,\nhdmi_drm_infoframe_pack() to pack the infoframe as per spec, in case of\nHDMI encoder.",
	"EDID":                "Blob property which contains the current EDID read from the sink. This\nis useful to parse sink identification information like vendor, model\nand serial. Drivers should update this property by calling\ndrm_connector_update_edid_property(), usually after having parsed\nthe EDID using drm_add_edid_modes(). Userspace cannot change this\nproperty.",
	"HDCP Content Type":   "This Enum property is used by the userspace to declare the content type\nof the display stream, to kernel. Here display stream stands for any\ndisplay content that userspace intended to display through HDCP\nencryption.\n\nContent Type of a stream is decided by the owner of the stream, as\n\"HDCP Type0\" or \"HDCP Type1\".\n\nThe value of the property can be one of the below:\n  - \"HDCP Type0\": DRM_MODE_HDCP_CONTENT_TYPE0 = 0\n  - \"HDCP Type1\": DRM_MODE_HDCP_CONTENT_TYPE1 = 1\n\nWhen kernel starts the HDCP authentication (see \"Content Protection\"\nfor details), it uses the content type in \"HDCP Content Type\"\nfor performing the HDCP authentication with the display sink.\n\nPlease note in HDCP spec versions, a link can be authenticated with\nHDCP 2.2 for Content Type 0/Content Type 1. Where as a link can be\nauthenticated with HDCP1.4 only for Content Type 0(though it is implicit\nin nature. As there is no reference for Content Type in HDCP1.4).\n\nHDCP2.2 authentication protocol itself takes the \"Content Type\" as a\nparameter, which is a input for the DP HDCP2.2 encryption algo.\n\nIn case of Type 0 content protection request, kernel driver can choose\neither of HDCP spec versions 1.4 and 2.2. When HDCP2.2 is used for\n\"HDCP Type 0\", a HDCP 2.2 capable repeater in the downstream can send\nthat content to a HDCP 1.4 authenticated HDCP sink (Type0 link).\nBut if the content is classified as \"HDCP Type 1\", above mentioned\nHDCP 2.2 repeater wont send the content to the HDCP sink as it can't\nauthenticate the HDCP1.4 capable sink for \"HDCP Type 1\".\n\nPlease note userspace can be ignorant of the HDCP versions used by the\nkernel driver to achieve the \"HDCP Content Type\".\n\nAt current scenario, classifying a content as Type 1 ensures that the\ncontent will be displayed only through the HDCP2.2 encrypted link.\n\nNote that the HDCP Content Type property is introduced at HDCP 2.2, and\ndefaults to type 0. It is only exposed by drivers supporting HDCP 2.2\n(hence supporting Type 0 and Type 1). Based on how next versions of\nHDCP specs are defined content Type could be used for higher versions\ntoo.\n\nIf content type is changed when \"Content Protection\" is not UNDESIRED,\nthen kernel will disable the HDCP and re-enable with new type in the\nsame atomic commit. And when \"Content Protection\" is ENABLED, it means\nthat link is HDCP authenticated and encrypted, for the transmission of\nthe Type of stream mentioned at \"HDCP Content Type\".",
	"HDR_OUTPUT_METADATA": "Connector property to enable userspace to send HDR Metadata to\ndriver. This metadata is based on the composition and blending\npolicies decided by user, taking into account the hardware and\nsink capabilities. The driver gets this metadata and creates a\nDynamic Range and Mastering Infoframe (DRM) in case of HDMI,\nSDP packet (Non-audio INFOFRAME SDP v1.3) for DP. This is then\nsent to sink. This notifies the sink of the upcoming frame's Color\nEncoding and Luminance parameters.\n\nUserspace first need to detect the HDR capabilities of sink by\nreading and parsing the EDID. Details of HDR metadata for HDMI\nare added in CTA 861.G spec. For DP , its defined in VESA DP\nStandard v1.4. It needs to then get the metadata information\nof the video/game/app content which are encoded in HDR (basically\nusing HDR transfer functions). With this information it needs to\ndecide on a blending policy and compose the relevant\nlayers/overlays into a common format. Once this blending is done,\nuserspace will be aware of the metadata of the composed frame to\nbe send to sink. It then uses this property to communicate this\nmetadata to driver which then make a Infoframe packet and sends\nto sink based on the type of encoder connected.\n\nUserspace will be responsible to do Tone mapping operation in case:\n\t- Some layers are HDR and others are SDR\n\t- HDR layers luminance is not same as sink\n\nIt will even need to do colorspace conversion and get all layers\nto one common colorspace for blending. It can use either GL, Media\nor display engine to get this done based on the capabilities of the\nassociated hardware.\n\nDriver expects metadata to be put in &struct hdr_output_metadata\nstructure from userspace. This is received as blob and stored in\n&drm_connector_state.hdr_output_metadata. It parses EDID and saves the\nsink metadata in &struct hdr_sink_metadata, as\n&drm_connector.hdr_sink_metadata.  Driver uses\ndrm_hdmi_infoframe_set_hdr_metadata() helper to set the HDR metadata,\nhdmi_drm_infoframe_pack() to pack the infoframe as per spec, in case of\nHDMI encoder.",
	"PATH":                "Connector path property to identify how this sink is physically\nconnected. Used by DP MST. This should be set by calling\ndrm_connector_set_path_property(), in the case of DP MST with the\npath property the MST manager created. Userspace cannot change this\nproperty.",
	"TILE":                "Connector tile group property to indicate how a set of DRM connector\ncompose together into one logical screen. This is used by both high-res\nexternal screens (often only using a single cable, but exposing multiple\nDP MST sinks), or high-res integrated panels (like dual-link DSI) which\nare not gen-locked. Note that for tiled panels which are genlocked, like\ndual-link LVDS or dual-link DSI, the driver should try to not expose the\ntiling and virtualise both &drm_crtc and &drm_plane if needed. Drivers\nshould update this value using drm_connector_set_tile_property().\nUserspace cannot change this property.",
	"link-status":         "Connector link-status property to indicate the status of link. The\ndefault value of link-status is \"GOOD\". If something fails during or\nafter modeset, the kernel driver may set this to \"BAD\" and issue a\nhotplug uevent. Drivers should update this value using\ndrm_connector_set_link_status_property().\n\nWhen user-space receives the hotplug uevent and detects a \"BAD\"\nlink-status, the sink doesn't receive pixels anymore (e.g. the screen\nbecomes completely black). The list of available modes may have\nchanged. User-space is expected to pick a new mode if the current one\nhas disappeared and perform a new modeset with link-status set to\n\"GOOD\" to re-enable the connector.\n\nIf multiple connectors share the same CRTC and one of them gets a \"BAD\"\nlink-status, the other are unaffected (ie. the sinks still continue to\nreceive pixels).\n\nWhen user-space performs an atomic commit on a connector with a \"BAD\"\nlink-status without resetting the property to \"GOOD\", the sink may\nstill not receive pixels. When user-space performs an atomic commit\nwhich resets the link-status property to \"GOOD\" without the\nALLOW_MODESET flag set, it might fail because a modeset is required.\n\nUser-space can only change link-status to \"GOOD\", changing it to \"BAD\"\nis a no-op.\n\nFor backwards compatibility with non-atomic userspace the kernel\ntries to automatically set the link-status back to \"GOOD\" in the\nSETCRTC IOCTL. This might fail if the mode is no longer valid, similar\nto how it might fail if a different screen has been connected in the\ninterim.",
	"max bpc":             "This range property is used by userspace to limit the bit depth. When\nused the driver would limit the bpc in accordance with the valid range\nsupported by the hardware and sink. Drivers to use the function\ndrm_connector_attach_max_bpc_property() to create and attach the\nproperty to the connector during initialization.",
	"non_desktop":         "Indicates the output should be ignored for purposes of displaying a\nstandard desktop environment or console. This is most likely because\nthe output device is not rectilinear.",
	"panel orientation":   "On some devices the LCD panel is mounted in the casing in such a way\nthat the up/top side of the panel does not match with the top side of\nthe device. Userspace can use this property to check for this.\nNote that input coordinates from touchscreens (input devices with\nINPUT_PROP_DIRECT) will still map 1:1 to the actual LCD panel\ncoordinates, so if userspace rotates the picture to adjust for\nthe orientation it must also apply the same transformation to the\ntouchscreen input coordinates. This property is initialized by calling\ndrm_connector_set_panel_orientation() or\ndrm_connector_set_panel_orientation_with_quirk()",
	"scaling mode":        "This property defines how a non-native mode is upscaled to the native\nmode of an LCD panel:\n\nNone:\n\tNo upscaling happens, scaling is left to the panel. Not all\n\tdrivers expose this mode.\nFull:\n\tThe output is upscaled to the full resolution of the panel,\n\tignoring the aspect ratio.\nCenter:\n\tNo upscaling happens, the output is centered within the native\n\tresolution the panel.\nFull aspect:\n\tThe output is upscaled to maximize either the width or height\n\twhile retaining the aspect ratio.\n\nThis property should be set up by calling\ndrm_connector_attach_scaling_mode_property(). Note that drivers\ncan also expose this property to external outputs, in which case they\nmust support \"None\", which should be the default (since external screens\nhave a built-in scaler).",
	"subconnector":        "This property is used by DVI-I, TVout and DisplayPort to indicate different\nconnector subtypes. Enum values more or less match with those from main\nconnector types.\nFor DVI-I and TVout there is also a matching property \"select subconnector\"\nallowing to switch between signal types.\nDP subconnector corresponds to a downstream port.",
	"PATH":                "Connector path property to identify how this sink is physically\nconnected. Used by DP MST. This should be set by calling\ndrm_connector_set_path_property(), in the case of DP MST with the\npath property the MST manager created. Userspace cannot change this\nproperty.",
	"Content Protection":  "This property is used by userspace to request the kernel protect future\ncontent communicated over the link. When requested, kernel will apply\nthe appropriate means of protection (most often HDCP), and use the\nproperty to tell userspace the protection is active.\n\nDrivers can set this up by calling\ndrm_connector_attach_content_protection_property() on initialization.\n\nThe value of this property can be one of the following:\n\nDRM_MODE_CONTENT_PROTECTION_UNDESIRED = 0\n\tThe link is not protected, content is transmitted in the clear.\nDRM_MODE_CONTENT_PROTECTION_DESIRED = 1\n\tUserspace has requested content protection, but the link is not\n\tcurrently protected. When in this state, kernel should enable\n\tContent Protection as soon as possible.\nDRM_MODE_CONTENT_PROTECTION_ENABLED = 2\n\tUserspace has requested content protection, and the link is\n\tprotected. Only the driver can set the property to this value.\n\tIf userspace attempts to set to ENABLED, kernel will return\n\t-EINVAL.\n\nA few guidelines:\n\n- DESIRED state should be preserved until userspace de-asserts it by\n  setting the property to UNDESIRED. This means ENABLED should only\n  transition to UNDESIRED when the user explicitly requests it.\n- If the state is DESIRED, kernel should attempt to re-authenticate the\n  link whenever possible. This includes across disable/enable, dpms,\n  hotplug, downstream device changes, link status failures, etc..\n- Kernel sends uevent with the connector id and property id through\n  @drm_hdcp_update_content_protection, upon below kernel triggered\n  scenarios:\n\n\t- DESIRED -> ENABLED (authentication success)\n\t- ENABLED -> DESIRED (termination of authentication)\n- Please note no uevents for userspace triggered property state changes,\n  which can't fail such as\n\n\t- DESIRED/ENABLED -> UNDESIRED\n\t- UNDESIRED -> DESIRED\n- Userspace is responsible for polling the property or listen to uevents\n  to determine when the value transitions from ENABLED to DESIRED.\n  This signifies the link is no longer protected and userspace should\n  take appropriate action (whatever that might be).",
}

M drmdoc/variable-refresh-properties.go => drmdoc/variable-refresh-properties.go +1 -1
@@ 3,6 3,6 @@
package drmdoc

var variableRefreshProperties = map[string]string{
	"vrr_capable": "Optional &drm_connector boolean property that drivers should attach\nwith drm_connector_attach_vrr_capable_property() on connectors that\ncould support variable refresh rates. Drivers should update the\nproperty value by calling drm_connector_set_vrr_capable_property().\n\nAbsence of the property should indicate absence of support.",
	"VRR_ENABLED": "Default &drm_crtc boolean property that notifies the driver that the\ncontent on the CRTC is suitable for variable refresh rate presentation.\nThe driver will take this property as a hint to enable variable\nrefresh rate support if the receiver supports it, ie. if the\n\"vrr_capable\" property is true on the &drm_connector object. The\nvertical front porch duration will be extended until page-flip or\ntimeout when enabled.\n\nThe minimum vertical front porch duration is defined as the vertical\nfront porch duration for the current mode.\n\nThe maximum vertical front porch duration is greater than or equal to\nthe minimum vertical front porch duration. The duration is derived\nfrom the minimum supported variable refresh rate for the connector.\n\nThe driver may place further restrictions within these minimum\nand maximum bounds.",
	"vrr_capable": "Optional &drm_connector boolean property that drivers should attach\nwith drm_connector_attach_vrr_capable_property() on connectors that\ncould support variable refresh rates. Drivers should update the\nproperty value by calling drm_connector_set_vrr_capable_property().\n\nAbsence of the property should indicate absence of support.",
}