From 098b8a0da40925a96f69f3cea4c55ce8ee5e9857 Mon Sep 17 00:00:00 2001 From: Simon Ser Date: Mon, 24 Oct 2022 10:39:23 +0200 Subject: [PATCH] drmdoc: update from drm-tip --- drmdoc/color-management-properties.go | 2 +- drmdoc/explicit-fencing-properties.go | 2 +- drmdoc/generate.go | 2 ++ drmdoc/hdmi-connector-properties.go | 2 +- drmdoc/standard-connector-properties.go | 5 +++-- drmdoc/standard-plane-properties.go | 3 ++- 6 files changed, 10 insertions(+), 6 deletions(-) diff --git a/drmdoc/color-management-properties.go b/drmdoc/color-management-properties.go index 969a3e6..afe88e3 100644 --- a/drmdoc/color-management-properties.go +++ b/drmdoc/color-management-properties.go @@ -8,6 +8,6 @@ var colorManagementProperties = map[string]string{ "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": "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.\n\nNote that for mostly historical reasons stemming from Xorg heritage,\nthis is also used to store the color map (also sometimes color lut, CLUT\nor color palette) for indexed formats like DRM_FORMAT_C8.", "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.", } diff --git a/drmdoc/explicit-fencing-properties.go b/drmdoc/explicit-fencing-properties.go index 9c9f34c..7a0d9b7 100644 --- a/drmdoc/explicit-fencing-properties.go +++ b/drmdoc/explicit-fencing-properties.go @@ -3,6 +3,6 @@ package drmdoc var explicitFencingProperties = map[string]string{ - "IN_FENCE_FD": "Use this property to pass a fence that DRM should wait on before\nproceeding with the Atomic Commit request and show the framebuffer for\nthe plane on the screen. The fence can be either a normal fence or a\nmerged one, the sync_file framework will handle both cases and use a\nfence_array if a merged fence is received. Passing -1 here means no\nfences to wait on.\n\nIf the Atomic Commit request has the DRM_MODE_ATOMIC_TEST_ONLY flag\nit will only check if the Sync File is a valid one.\n\nOn the driver side the fence is stored on the @fence parameter of\n&struct drm_plane_state. Drivers which also support implicit fencing\nshould set the implicit fence using drm_atomic_set_fence_for_plane(),\nto make sure there's consistent behaviour between drivers in precedence\nof implicit vs. explicit fencing.", + "IN_FENCE_FD": "Use this property to pass a fence that DRM should wait on before\nproceeding with the Atomic Commit request and show the framebuffer for\nthe plane on the screen. The fence can be either a normal fence or a\nmerged one, the sync_file framework will handle both cases and use a\nfence_array if a merged fence is received. Passing -1 here means no\nfences to wait on.\n\nIf the Atomic Commit request has the DRM_MODE_ATOMIC_TEST_ONLY flag\nit will only check if the Sync File is a valid one.\n\nOn the driver side the fence is stored on the @fence parameter of\n&struct drm_plane_state. Drivers which also support implicit fencing\nshould extract the implicit fence using drm_gem_plane_helper_prepare_fb(),\nto make sure there's consistent behaviour between drivers in precedence\nof implicit vs. explicit fencing.", "OUT_FENCE_PTR": "Use this property to pass a file descriptor pointer to DRM. Once the\nAtomic Commit request call returns OUT_FENCE_PTR will be filled with\nthe file descriptor number of a Sync File. This Sync File contains the\nCRTC fence that will be signaled when all framebuffers present on the\nAtomic Commit * request for that given CRTC are scanned out on the\nscreen.\n\nThe Atomic Commit request fails if a invalid pointer is passed. If the\nAtomic Commit request fails for any other reason the out fence fd\nreturned will be -1. On a Atomic Commit with the\nDRM_MODE_ATOMIC_TEST_ONLY flag the out fence will also be set to -1.\n\nNote that out-fences don't have a special interface to drivers and are\ninternally represented by a &struct drm_pending_vblank_event in struct\n&drm_crtc_state, which is also used by the nonblocking atomic commit\nhelpers and for the DRM event handling for existing userspace.", } diff --git a/drmdoc/generate.go b/drmdoc/generate.go index 7aabd33..f1eac0b 100644 --- a/drmdoc/generate.go +++ b/drmdoc/generate.go @@ -144,6 +144,8 @@ func main() { log.Fatal(err) } + // TODO: handle headings with multiple props in them such as + // "privacy-screen sw-state, privacy-screen hw-state" props := parseProps(doc) symbol := titleToSymbol(outTitle) diff --git a/drmdoc/hdmi-connector-properties.go b/drmdoc/hdmi-connector-properties.go index ec5de12..b796daf 100644 --- a/drmdoc/hdmi-connector-properties.go +++ b/drmdoc/hdmi-connector-properties.go @@ -3,5 +3,5 @@ package drmdoc var hdmiConnectorProperties = map[string]string{ - "content type": "Indicates content type setting to be used in HDMI infoframes to indicate\ncontent type for the external device, so that it adjusts its display\nsettings accordingly.\n\nThe value of this property can be one of the following:\n\nNo Data:\n\tContent type is unknown\nGraphics:\n\tContent type is graphics\nPhoto:\n\tContent type is photo\nCinema:\n\tContent type is cinema\nGame:\n\tContent type is game\n\nDrivers can set up this property by calling\ndrm_connector_attach_content_type_property(). Decoding to\ninfoframe values is done through drm_hdmi_avi_infoframe_content_type().", + "content type": "Indicates content type setting to be used in HDMI infoframes to indicate\ncontent type for the external device, so that it adjusts its display\nsettings accordingly.\n\nThe value of this property can be one of the following:\n\nNo Data:\n\tContent type is unknown\nGraphics:\n\tContent type is graphics\nPhoto:\n\tContent type is photo\nCinema:\n\tContent type is cinema\nGame:\n\tContent type is game\n\nThe meaning of each content type is defined in CTA-861-G table 15.\n\nDrivers can set up this property by calling\ndrm_connector_attach_content_type_property(). Decoding to\ninfoframe values is done through drm_hdmi_avi_infoframe_content_type().", } diff --git a/drmdoc/standard-connector-properties.go b/drmdoc/standard-connector-properties.go index 44b665b..f4d595f 100644 --- a/drmdoc/standard-connector-properties.go +++ b/drmdoc/standard-connector-properties.go @@ -15,6 +15,7 @@ var standardConnectorProperties = map[string]string{ "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.", + "privacy-screen sw-state, privacy-screen hw-state": "These 2 optional properties can be used to query the state of the\nelectronic privacy screen that is available on some displays; and in\nsome cases also control the state. If a driver implements these\nproperties then both properties must be present.\n\n\"privacy-screen hw-state\" is read-only and reflects the actual state\nof the privacy-screen, possible values: \"Enabled\", \"Disabled,\n\"Enabled-locked\", \"Disabled-locked\". The locked states indicate\nthat the state cannot be changed through the DRM API. E.g. there\nmight be devices where the firmware-setup options, or a hardware\nslider-switch, offer always on / off modes.\n\n\"privacy-screen sw-state\" can be set to change the privacy-screen state\nwhen not locked. In this case the driver must update the hw-state\nproperty to reflect the new state on completion of the commit of the\nsw-state property. Setting the sw-state property when the hw-state is\nlocked must be interpreted by the driver as a request to change the\nstate to the set state when the hw-state becomes unlocked. E.g. if\n\"privacy-screen hw-state\" is \"Enabled-locked\" and the sw-state\ngets set to \"Disabled\" followed by the user unlocking the state by\nchanging the slider-switch position, then the driver must set the\nstate to \"Disabled\" upon receiving the unlock event.\n\nIn some cases the privacy-screen's actual state might change outside of\ncontrol of the DRM code. E.g. there might be a firmware handled hotkey\nwhich toggles the actual state, or the actual state might be changed\nthrough another userspace API such as writing /proc/acpi/ibm/lcdshadow.\nIn this case the driver must update both the hw-state and the sw-state\nto reflect the new value, overwriting any pending state requests in the\nsw-state. Any pending sw-state requests are thus discarded.\n\nNote that the ability for the state to change outside of control of\nthe DRM master process means that userspace must not cache the value\nof the sw-state. Caching the sw-state value and including it in later\natomic commits may lead to overriding a state change done through e.g.\na firmware handled hotkey. Therefor userspace must not include the\nprivacy-screen sw-state in an atomic commit unless it wants to change\nits value.", + "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.", } diff --git a/drmdoc/standard-plane-properties.go b/drmdoc/standard-plane-properties.go index daa4aa2..08096f2 100644 --- a/drmdoc/standard-plane-properties.go +++ b/drmdoc/standard-plane-properties.go @@ -3,5 +3,6 @@ package drmdoc var standardPlaneProperties = map[string]string{ - "IN_FORMATS": "Blob property which contains the set of buffer format and modifier\npairs supported by this plane. The blob is a struct\ndrm_format_modifier_blob. Without this property the plane doesn't\nsupport buffers with modifiers. Userspace cannot change this property.", + "IN_FORMATS": "Blob property which contains the set of buffer format and modifier\npairs supported by this plane. The blob is a struct\ndrm_format_modifier_blob. Without this property the plane doesn't\nsupport buffers with modifiers. Userspace cannot change this property.\n\nNote that userspace can check the &DRM_CAP_ADDFB2_MODIFIERS driver\ncapability for general modifier support. If this flag is set then every\nplane will have the IN_FORMATS property, even when it only supports\nDRM_FORMAT_MOD_LINEAR. Before linux kernel release v5.1 there have been\nvarious bugs in this area with inconsistencies between the capability\nflag and per-plane properties.", + "type": "Immutable property describing the type of the plane.\n\nFor user-space which has enabled the &DRM_CLIENT_CAP_ATOMIC capability,\nthe plane type is just a hint and is mostly superseded by atomic\ntest-only commits. The type hint can still be used to come up more\neasily with a plane configuration accepted by the driver.\n\nThe value of this property can be one of the following:\n\n\"Primary\":\n To light up a CRTC, attaching a primary plane is the most likely to\n work if it covers the whole CRTC and doesn't have scaling or\n cropping set up.\n\n Drivers may support more features for the primary plane, user-space\n can find out with test-only atomic commits.\n\n Some primary planes are implicitly used by the kernel in the legacy\n IOCTLs &DRM_IOCTL_MODE_SETCRTC and &DRM_IOCTL_MODE_PAGE_FLIP.\n Therefore user-space must not mix explicit usage of any primary\n plane (e.g. through an atomic commit) with these legacy IOCTLs.\n\n\"Cursor\":\n To enable this plane, using a framebuffer configured without scaling\n or cropping and with the following properties is the most likely to\n work:\n\n - If the driver provides the capabilities &DRM_CAP_CURSOR_WIDTH and\n &DRM_CAP_CURSOR_HEIGHT, create the framebuffer with this size.\n Otherwise, create a framebuffer with the size 64x64.\n - If the driver doesn't support modifiers, create a framebuffer with\n a linear layout. Otherwise, use the IN_FORMATS plane property.\n\n Drivers may support more features for the cursor plane, user-space\n can find out with test-only atomic commits.\n\n Some cursor planes are implicitly used by the kernel in the legacy\n IOCTLs &DRM_IOCTL_MODE_CURSOR and &DRM_IOCTL_MODE_CURSOR2.\n Therefore user-space must not mix explicit usage of any cursor\n plane (e.g. through an atomic commit) with these legacy IOCTLs.\n\n Some drivers may support cursors even if no cursor plane is exposed.\n In this case, the legacy cursor IOCTLs can be used to configure the\n cursor.\n\n\"Overlay\":\n Neither primary nor cursor.\n\n Overlay planes are the only planes exposed when the\n &DRM_CLIENT_CAP_UNIVERSAL_PLANES capability is disabled.", } -- 2.45.2