Drivers may need to expose additional parameters to applications than those described in the previous sections. KMS supports attaching properties to CRTCs, connectors and planes and offers a userspace API to list, get and set the property values.
Properties are identified by a name that uniquely defines the property purpose, and store an associated value. For all property types except blob properties the value is a 64-bit unsigned integer.
KMS differentiates between properties and property instances. Drivers first create properties and then create and associate individual instances of those properties to objects. A property can be instantiated multiple times and associated with different objects. Values are stored in property instances, and all other property information are stored in the property and shared between all instances of the property.
Every property is created with a type that influences how the KMS core handles the property. Supported property types are
Range properties report their minimum and maximum admissible values. The KMS core verifies that values set by application fit in that range.
Enumerated properties take a numerical value that ranges from 0 to the number of enumerated values defined by the property minus one, and associate a free-formed string name to each value. Applications can retrieve the list of defined value-name pairs and use the numerical value to get and set property instance values.
Bitmask properties are enumeration properties that additionally restrict all enumerated values to the 0..63 range. Bitmask property instance values combine one or more of the enumerated bits defined by the property.
Blob properties store a binary blob without any format restriction. The binary blobs are created as KMS standalone objects, and blob property instance values store the ID of their associated blob object.
Blob properties are only used for the connector EDID property and cannot be created by drivers.
To create a property drivers call one of the following functions depending on the property type. All property creation functions take property flags and name, as well as type-specific arguments.
struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
const char *name,
uint64_t min, uint64_t max);Create a range property with the given minimum and maximum values.
struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
const char *name,
const struct drm_prop_enum_list *props,
int num_values);Create an enumerated property. The props
argument points to an array of num_values
value-name pairs.
struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
int flags, const char *name,
const struct drm_prop_enum_list *props,
int num_values);Create a bitmask property. The props
argument points to an array of num_values
value-name pairs.
Properties can additionally be created as immutable, in which case they will be read-only for applications but can be modified by the driver. To create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE flag at property creation time.
When no array of value-name pairs is readily available at property
creation time for enumerated or range properties, drivers can create
the property using the drm_property_create function
and manually add enumeration value-name pairs by calling the
drm_property_add_enum function. Care must be taken to
properly specify the property type through the flags
argument.
After creating properties drivers can attach property instances to CRTC,
connector and plane objects by calling the
drm_object_attach_property. The function takes a
pointer to the target object, a pointer to the previously created property
and an initial instance value.
The following table gives description of drm properties exposed by various modules/drivers.
| Owner Module/Drivers | Group | Property Name | Type | Property Values | Object attached | Description/Restrictions |
| DRM | Generic | “EDID” | BLOB | IMMUTABLE | 0 | Connector | Contains id of edid blob ptr object. |
| “DPMS” | ENUM | { “On”, “Standby”, “Suspend”, “Off” } | Connector | Contains DPMS operation mode value. | ||
| Plane | “type” | ENUM | IMMUTABLE | { "Overlay", "Primary", "Cursor" } | Plane | Plane type | |
| DVI-I | “subconnector” | ENUM | { “Unknown”, “DVI-D”, “DVI-A” } | Connector | TBD | |
| “select subconnector” | ENUM | { “Automatic”, “DVI-D”, “DVI-A” } | Connector | TBD | ||
| TV | “subconnector” | ENUM | { "Unknown", "Composite", "SVIDEO", "Component", "SCART" } | Connector | TBD | |
| “select subconnector” | ENUM | { "Automatic", "Composite", "SVIDEO", "Component", "SCART" } | Connector | TBD | ||
| “mode” | ENUM | { "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc. | Connector | TBD | ||
| “left margin” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “right margin” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “top margin” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “bottom margin” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “brightness” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “contrast” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “flicker reduction” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “overscan” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “saturation” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| “hue” | RANGE | Min=0, Max=100 | Connector | TBD | ||
| Optional | “scaling mode” | ENUM | { "None", "Full", "Center", "Full aspect" } | Connector | TBD | |
| “dirty” | ENUM | IMMUTABLE | { "Off", "On", "Annotate" } | Connector | TBD | ||
| i915 | Generic | "Broadcast RGB" | ENUM | { "Automatic", "Full", "Limited 16:235" } | Connector | TBD |
| “audio” | ENUM | { "force-dvi", "off", "auto", "on" } | Connector | TBD | ||
| Standard name as in DRM | Standard type as in DRM | Standard value as in DRM | Standard Object as in DRM | TBD | ||
| SDVO-TV | “mode” | ENUM | { "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc. | Connector | TBD | |
| "left_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| "right_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| "top_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| "bottom_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “hpos” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “vpos” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “contrast” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “saturation” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “hue” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “sharpness” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “flicker_filter” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “flicker_filter_adaptive” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “flicker_filter_2d” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “tv_chroma_filter” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “tv_luma_filter” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “dot_crawl” | RANGE | Min=0, Max=1 | Connector | TBD | ||
| SDVO-TV/LVDS | “brightness” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | |
| CDV gma-500 | Generic | "Broadcast RGB" | ENUM | { “Full”, “Limited 16:235” } | Connector | TBD |
| "Broadcast RGB" | ENUM | { “off”, “auto”, “on” } | Connector | TBD | ||
| Standard name as in DRM | Standard type as in DRM | Standard value as in DRM | Standard Object as in DRM | TBD | ||
| Poulsbo | Generic | “backlight” | RANGE | Min=0, Max=100 | Connector | TBD |
| Standard name as in DRM | Standard type as in DRM | Standard value as in DRM | Standard Object as in DRM | TBD | ||
| SDVO-TV | “mode” | ENUM | { "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc. | Connector | TBD | |
| "left_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| "right_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| "top_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| "bottom_margin" | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “hpos” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “vpos” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “contrast” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “saturation” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “hue” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “sharpness” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “flicker_filter” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “flicker_filter_adaptive” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “flicker_filter_2d” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “tv_chroma_filter” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “tv_luma_filter” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | ||
| “dot_crawl” | RANGE | Min=0, Max=1 | Connector | TBD | ||
| SDVO-TV/LVDS | “brightness” | RANGE | Min=0, Max= SDVO dependent | Connector | TBD | |
| armada | CRTC | "CSC_YUV" | ENUM | { "Auto" , "CCIR601", "CCIR709" } | CRTC | TBD |
| "CSC_RGB" | ENUM | { "Auto", "Computer system", "Studio" } | CRTC | TBD | ||
| Overlay | "colorkey" | RANGE | Min=0, Max=0xffffff | Plane | TBD | |
| "colorkey_min" | RANGE | Min=0, Max=0xffffff | Plane | TBD | ||
| "colorkey_max" | RANGE | Min=0, Max=0xffffff | Plane | TBD | ||
| "colorkey_val" | RANGE | Min=0, Max=0xffffff | Plane | TBD | ||
| "colorkey_alpha" | RANGE | Min=0, Max=0xffffff | Plane | TBD | ||
| "colorkey_mode" | ENUM | { "disabled", "Y component", "U component" , "V component", "RGB", “R component", "G component", "B component" } | Plane | TBD | ||
| "brightness" | RANGE | Min=0, Max=256 + 255 | Plane | TBD | ||
| "contrast" | RANGE | Min=0, Max=0x7fff | Plane | TBD | ||
| "saturation" | RANGE | Min=0, Max=0x7fff | Plane | TBD | ||
| exynos | CRTC | “mode” | ENUM | { "normal", "blank" } | CRTC | TBD |
| Overlay | “zpos” | RANGE | Min=0, Max=MAX_PLANE-1 | Plane | TBD | |
| i2c/ch7006_drv | Generic | “scale” | RANGE | Min=0, Max=2 | Connector | TBD |
| TV | Standard names as in DRM | Standard types as in DRM | Standard Values as in DRM | Standard object as in DRM | TBD | |
| “mode” | ENUM | { "PAL", "PAL-M","PAL-N"}, ”PAL-Nc" , "PAL-60", "NTSC-M", "NTSC-J" } | Connector | TBD | ||
| nouveau | NV10 Overlay | "colorkey" | RANGE | Min=0, Max=0x01ffffff | Plane | TBD |
| “contrast” | RANGE | Min=0, Max=8192-1 | Plane | TBD | ||
| “brightness” | RANGE | Min=0, Max=1024 | Plane | TBD | ||
| “hue” | RANGE | Min=0, Max=359 | Plane | TBD | ||
| “saturation” | RANGE | Min=0, Max=8192-1 | Plane | TBD | ||
| “iturbt_709” | RANGE | Min=0, Max=1 | Plane | TBD | ||
| Nv04 Overlay | “colorkey” | RANGE | Min=0, Max=0x01ffffff | Plane | TBD | |
| “brightness” | RANGE | Min=0, Max=1024 | Plane | TBD | ||
| Display | “dithering mode” | ENUM | { "auto", "off", "on" } | Connector | TBD | |
| “dithering depth” | ENUM | { "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" } | Connector | TBD | ||
| “underscan” | ENUM | { "auto", "6 bpc", "8 bpc" } | Connector | TBD | ||
| “underscan hborder” | RANGE | Min=0, Max=128 | Connector | TBD | ||
| “underscan vborder” | RANGE | Min=0, Max=128 | Connector | TBD | ||
| “vibrant hue” | RANGE | Min=0, Max=180 | Connector | TBD | ||
| “color vibrance” | RANGE | Min=0, Max=200 | Connector | TBD | ||
| Generic | Standard name as in DRM | Standard type as in DRM | Standard value as in DRM | Standard Object as in DRM | TBD | |
| omap | Generic | “rotation” | BITMASK | { 0, "rotate-0" }, { 1, "rotate-90" }, { 2, "rotate-180" }, { 3, "rotate-270" }, { 4, "reflect-x" }, { 5, "reflect-y" } | CRTC, Plane | TBD |
| “zorder” | RANGE | Min=0, Max=3 | CRTC, Plane | TBD | ||
| qxl | Generic | “hotplug_mode_update" | RANGE | Min=0, Max=1 | Connector | TBD |
| radeon | DVI-I | “coherent” | RANGE | Min=0, Max=1 | Connector | TBD |
| DAC enable load detect | “load detection” | RANGE | Min=0, Max=1 | Connector | TBD | |
| TV Standard | "tv standard" | ENUM | { "ntsc", "pal", "pal-m", "pal-60", "ntsc-j" , "scart-pal", "pal-cn", "secam" } | Connector | TBD | |
| legacy TMDS PLL detect | "tmds_pll" | ENUM | { "driver", "bios" } | - | TBD | |
| Underscan | "underscan" | ENUM | { "off", "on", "auto" } | Connector | TBD | |
| "underscan hborder" | RANGE | Min=0, Max=128 | Connector | TBD | ||
| "underscan vborder" | RANGE | Min=0, Max=128 | Connector | TBD | ||
| Audio | “audio” | ENUM | { "off", "on", "auto" } | Connector | TBD | |
| FMT Dithering | “dither” | ENUM | { "off", "on" } | Connector | TBD | |
| Generic | Standard name as in DRM | Standard type as in DRM | Standard value as in DRM | Standard Object as in DRM | TBD | |
| rcar-du | Generic | "alpha" | RANGE | Min=0, Max=255 | Plane | TBD |
| "colorkey" | RANGE | Min=0, Max=0x01ffffff | Plane | TBD | ||
| "zpos" | RANGE | Min=1, Max=7 | Plane | TBD |