Commit c8458c7e authored by Daniel Vetter's avatar Daniel Vetter

drm/doc: Polish docs for drm_property&drm_property_blob

- remove kerneldoc for drm-internal functions
- drm_property_replace_global_blob isn't actually atomic, and doesn't
  need to be. Update docs&comments to match
- document all the types and try to link things a bit better
- nits all over

v2: Appease checkpatch in the moved code (Archit)
Reviewed-by: default avatarArchit Taneja <architt@codeaurora.org>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20160829082757.17913-9-daniel.vetter@ffwll.ch
parent 77953bd1
...@@ -304,94 +304,12 @@ KMS Locking ...@@ -304,94 +304,12 @@ KMS Locking
KMS Properties KMS Properties
============== ==============
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
DRM_MODE_PROP_RANGE
Range properties report their minimum and maximum admissible values.
The KMS core verifies that values set by application fit in that
range.
DRM_MODE_PROP_ENUM
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.
DRM_MODE_PROP_BITMASK
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.
DRM_MODE_PROP_BLOB
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 :c:func:`drm_property_create()` function and
manually add enumeration value-name pairs by calling the
:c:func:`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
:c:func:`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.
Property Types and Blob Property Support Property Types and Blob Property Support
---------------------------------------- ----------------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_property.c
:doc: overview
.. kernel-doc:: include/drm/drm_property.h .. kernel-doc:: include/drm/drm_property.h
:internal: :internal:
......
This diff is collapsed.
...@@ -27,33 +27,192 @@ ...@@ -27,33 +27,192 @@
#include <linux/ctype.h> #include <linux/ctype.h>
#include <drm/drm_mode_object.h> #include <drm/drm_mode_object.h>
struct drm_property_blob { /**
struct drm_mode_object base; * struct drm_property_enum - symbolic values for enumerations
struct drm_device *dev; * @value: numeric property value for this enum entry
struct list_head head_global; * @head: list of enum values, linked to enum_list in &drm_property
struct list_head head_file; * @name: symbolic name for the enum
size_t length; *
unsigned char data[]; * For enumeration and bitmask properties this structure stores the symbolic
}; * decoding for each value. This is used for example for the rotation property.
*/
struct drm_property_enum { struct drm_property_enum {
uint64_t value; uint64_t value;
struct list_head head; struct list_head head;
char name[DRM_PROP_NAME_LEN]; char name[DRM_PROP_NAME_LEN];
}; };
/**
* struct drm_property - modeset object property
*
* This structure represent a modeset object property. It combines both the name
* of the property with the set of permissible values. This means that when a
* driver wants to use a property with the same name on different objects, but
* with different value ranges, then it must create property for each one. An
* example would be rotation of &drm_plane, when e.g. the primary plane cannot
* be rotated. But if both the name and the value range match, then the same
* property structure can be instantiated multiple times for the same object.
* Userspace must be able to cope with this and cannot assume that the same
* symbolic property will have the same modeset object ID on all modeset
* objects.
*
* Properties are created by one of the special functions, as explained in
* detail in the @flags structure member.
*
* To actually expose a property it must be attached to each object using
* drm_object_attach_property(). Currently properties can only be attached to
* &drm_connector, &drm_crtc and &drm_plane.
*
* Properties are also used as the generic metadatatransport for the atomic
* IOCTL. Everything that was set directly in structures in the legacy modeset
* IOCTLs (like the plane source or destination windows, or e.g. the links to
* the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.
*/
struct drm_property { struct drm_property {
/**
* @head: per-device list of properties, for cleanup.
*/
struct list_head head; struct list_head head;
/**
* @base: base KMS object
*/
struct drm_mode_object base; struct drm_mode_object base;
/**
* @flags:
*
* Property flags and type. A property needs to be one of the following
* types:
*
* DRM_MODE_PROP_RANGE
* Range properties report their minimum and maximum admissible unsigned values.
* The KMS core verifies that values set by application fit in that
* range. The range is unsigned. Range properties are created using
* drm_property_create_range().
*
* DRM_MODE_PROP_SIGNED_RANGE
* Range properties report their minimum and maximum admissible unsigned values.
* The KMS core verifies that values set by application fit in that
* range. The range is signed. Range properties are created using
* drm_property_create_signed_range().
*
* DRM_MODE_PROP_ENUM
* 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. Enum
* properties are created using drm_property_create_enum().
*
* DRM_MODE_PROP_BITMASK
* 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. Bitmask properties are created using
* drm_property_create_bitmask().
*
* DRM_MODE_PROB_OBJECT
* Object properties are used to link modeset objects. This is used
* extensively in the atomic support to create the display pipeline,
* by linking &drm_framebuffer to &drm_plane, &drm_plane to
* &drm_crtc and &drm_connector to &drm_crtc. An object property can
* only link to a specific type of &drm_mode_object, this limit is
* enforced by the core. Object properties are created using
* drm_property_create_object().
*
* Object properties work like blob properties, but in a more
* general fashion. They are limited to atomic drivers and must have
* the DRM_MODE_PROP_ATOMIC flag set.
*
* DRM_MODE_PROP_BLOB
* 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 created by calling
* drm_property_create() with DRM_MODE_PROP_BLOB as the type.
*
* Actual blob objects to contain blob data are created using
* drm_property_create_blob(), or through the corresponding IOCTL.
*
* Besides the built-in limit to only accept blob objects blob
* properties work exactly like object properties. The only reasons
* blob properties exist is backwards compatibility with existing
* userspace.
*
* In addition a property can have any combination of the below flags:
*
* DRM_MODE_PROP_ATOMIC
* Set for properties which encode atomic modeset state. Such
* properties are not exposed to legacy userspace.
*
* DRM_MODE_PROP_IMMUTABLE
* Set for properties where userspace cannot be changed by
* userspace. The kernel is allowed to update the value of these
* properties. This is generally used to expose probe state to
* usersapce, e.g. the EDID, or the connector path property on DP
* MST sinks.
*/
uint32_t flags; uint32_t flags;
/**
* @name: symbolic name of the properties
*/
char name[DRM_PROP_NAME_LEN]; char name[DRM_PROP_NAME_LEN];
/**
* @num_values: size of the @values array.
*/
uint32_t num_values; uint32_t num_values;
/**
* @values:
*
* Array with limits and values for the property. The
* interpretation of these limits is dependent upon the type per @flags.
*/
uint64_t *values; uint64_t *values;
/**
* @dev: DRM device
*/
struct drm_device *dev; struct drm_device *dev;
/**
* @enum_list:
*
* List of &drm_prop_enum_list structures with the symbolic names for
* enum and bitmask values.
*/
struct list_head enum_list; struct list_head enum_list;
}; };
/**
* struct drm_property_blob - Blob data for &drm_property
* @base: base KMS object
* @dev: DRM device
* @head_global: entry on the global blob list in &drm_mode_config
* property_blob_list.
* @head_file: entry on the per-file blob list in &drm_file blobs list.
* @length: size of the blob in bytes, invariant over the lifetime of the object
* @data: actual data, embedded at the end of this structure
*
* Blobs are used to store bigger values than what fits directly into the 64
* bits available for a &drm_property.
*
* Blobs are reference counted using drm_property_reference_blob() and
* drm_property_unreference_blob(). They are created using
* drm_property_create_blob().
*/
struct drm_property_blob {
struct drm_mode_object base;
struct drm_device *dev;
struct list_head head_global;
struct list_head head_file;
size_t length;
unsigned char data[];
};
struct drm_prop_enum_list { struct drm_prop_enum_list {
int type; int type;
char *name; char *name;
...@@ -61,8 +220,16 @@ struct drm_prop_enum_list { ...@@ -61,8 +220,16 @@ struct drm_prop_enum_list {
#define obj_to_property(x) container_of(x, struct drm_property, base) #define obj_to_property(x) container_of(x, struct drm_property, base)
/**
* drm_property_type_is - check the type of a property
* @property: property to check
* @type: property type to compare with
*
* This is a helper function becauase the uapi encoding of property types is
* a bit special for historical reasons.
*/
static inline bool drm_property_type_is(struct drm_property *property, static inline bool drm_property_type_is(struct drm_property *property,
uint32_t type) uint32_t type)
{ {
/* instanceof for props.. handles extended type vs original types: */ /* instanceof for props.. handles extended type vs original types: */
if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE) if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
...@@ -109,8 +276,15 @@ int drm_property_replace_global_blob(struct drm_device *dev, ...@@ -109,8 +276,15 @@ int drm_property_replace_global_blob(struct drm_device *dev,
struct drm_property_blob *drm_property_reference_blob(struct drm_property_blob *blob); struct drm_property_blob *drm_property_reference_blob(struct drm_property_blob *blob);
void drm_property_unreference_blob(struct drm_property_blob *blob); void drm_property_unreference_blob(struct drm_property_blob *blob);
/**
* drm_connector_find - find property object
* @dev: DRM device
* @id: property object id
*
* This function looks up the property object specified by id and returns it.
*/
static inline struct drm_property *drm_property_find(struct drm_device *dev, static inline struct drm_property *drm_property_find(struct drm_device *dev,
uint32_t id) uint32_t id)
{ {
struct drm_mode_object *mo; struct drm_mode_object *mo;
mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PROPERTY); mo = drm_mode_object_find(dev, id, DRM_MODE_OBJECT_PROPERTY);
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment