include/drm/drm_mode_object.h

0001 /*
0002  * Copyright (c) 2016 Intel Corporation
0003  *
0004  * Permission to use, copy, modify, distribute, and sell this software and its
0005  * documentation for any purpose is hereby granted without fee, provided that
0006  * the above copyright notice appear in all copies and that both that copyright
0007  * notice and this permission notice appear in supporting documentation, and
0008  * that the name of the copyright holders not be used in advertising or
0009  * publicity pertaining to distribution of the software without specific,
0010  * written prior permission.  The copyright holders make no representations
0011  * about the suitability of this software for any purpose.  It is provided "as
0012  * is" without express or implied warranty.
0013  *
0014  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
0015  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
0016  * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
0017  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
0018  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
0019  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
0020  * OF THIS SOFTWARE.
0021  */
0022
0023 #ifndef __DRM_MODESET_H__
0024 #define __DRM_MODESET_H__
0025
0026 #include <linux/kref.h>
0027 #include <drm/drm_lease.h>
0028 struct drm_object_properties;
0029 struct drm_property;
0030 struct drm_device;
0031 struct drm_file;
0032
0033 /**
0034  * struct drm_mode_object - base structure for modeset objects
0035  * @id: userspace visible identifier
0036  * @type: type of the object, one of DRM_MODE_OBJECT\_\*
0037  * @properties: properties attached to this object, including values
0038  * @refcount: reference count for objects which with dynamic lifetime
0039  * @free_cb: free function callback, only set for objects with dynamic lifetime
0040  *
0041  * Base structure for modeset objects visible to userspace. Objects can be
0042  * looked up using drm_mode_object_find(). Besides basic uapi interface
0043  * properties like @id and @type it provides two services:
0044  *
0045  * - It tracks attached properties and their values. This is used by &drm_crtc,
0046  *   &drm_plane and &drm_connector. Properties are attached by calling
0047  *   drm_object_attach_property() before the object is visible to userspace.
0048  *
0049  * - For objects with dynamic lifetimes (as indicated by a non-NULL @free_cb) it
0050  *   provides reference counting through drm_mode_object_get() and
0051  *   drm_mode_object_put(). This is used by &drm_framebuffer, &drm_connector
0052  *   and &drm_property_blob. These objects provide specialized reference
0053  *   counting wrappers.
0054  */
0055 struct drm_mode_object {
0056     uint32_t id;
0057     uint32_t type;
0058     struct drm_object_properties *properties;
0059     struct kref refcount;
0060     void (*free_cb)(struct kref *kref);
0061 };
0062
0063 #define DRM_OBJECT_MAX_PROPERTY 24
0064 /**
0065  * struct drm_object_properties - property tracking for &drm_mode_object
0066  */
0067 struct drm_object_properties {
0068     /**
0069      * @count: number of valid properties, must be less than or equal to
0070      * DRM_OBJECT_MAX_PROPERTY.
0071      */
0072
0073     int count;
0074     /**
0075      * @properties: Array of pointers to &drm_property.
0076      *
0077      * NOTE: if we ever start dynamically destroying properties (ie.
0078      * not at drm_mode_config_cleanup() time), then we'd have to do
0079      * a better job of detaching property from mode objects to avoid
0080      * dangling property pointers:
0081      */
0082     struct drm_property *properties[DRM_OBJECT_MAX_PROPERTY];
0083
0084     /**
0085      * @values: Array to store the property values, matching @properties. Do
0086      * not read/write values directly, but use
0087      * drm_object_property_get_value() and drm_object_property_set_value().
0088      *
0089      * Note that atomic drivers do not store mutable properties in this
0090      * array, but only the decoded values in the corresponding state
0091      * structure. The decoding is done using the &drm_crtc.atomic_get_property and
0092      * &drm_crtc.atomic_set_property hooks for &struct drm_crtc. For
0093      * &struct drm_plane the hooks are &drm_plane_funcs.atomic_get_property and
0094      * &drm_plane_funcs.atomic_set_property. And for &struct drm_connector
0095      * the hooks are &drm_connector_funcs.atomic_get_property and
0096      * &drm_connector_funcs.atomic_set_property .
0097      *
0098      * Hence atomic drivers should not use drm_object_property_set_value()
0099      * and drm_object_property_get_value() on mutable objects, i.e. those
0100      * without the DRM_MODE_PROP_IMMUTABLE flag set.
0101      *
0102      * For atomic drivers the default value of properties is stored in this
0103      * array, so drm_object_property_get_default_value can be used to
0104      * retrieve it.
0105      */
0106     uint64_t values[DRM_OBJECT_MAX_PROPERTY];
0107 };
0108
0109 /* Avoid boilerplate.  I'm tired of typing. */
0110 #define DRM_ENUM_NAME_FN(fnname, list)              \
0111     const char *fnname(int val)             \
0112     {                           \
0113         int i;                      \
0114         for (i = 0; i < ARRAY_SIZE(list); i++) {    \
0115             if (list[i].type == val)        \
0116                 return list[i].name;        \
0117         }                       \
0118         return "(unknown)";             \
0119     }
0120
0121 struct drm_mode_object *drm_mode_object_find(struct drm_device *dev,
0122                          struct drm_file *file_priv,
0123                          uint32_t id, uint32_t type);
0124 void drm_mode_object_get(struct drm_mode_object *obj);
0125 void drm_mode_object_put(struct drm_mode_object *obj);
0126
0127 int drm_object_property_set_value(struct drm_mode_object *obj,
0128                   struct drm_property *property,
0129                   uint64_t val);
0130 int drm_object_property_get_value(struct drm_mode_object *obj,
0131                   struct drm_property *property,
0132                   uint64_t *value);
0133 int drm_object_property_get_default_value(struct drm_mode_object *obj,
0134                       struct drm_property *property,
0135                       uint64_t *val);
0136
0137 void drm_object_attach_property(struct drm_mode_object *obj,
0138                 struct drm_property *property,
0139                 uint64_t init_val);
0140
0141 bool drm_mode_object_lease_required(uint32_t type);
0142 #endif