drivers/gpu/drm/drm_property.c

   1 /*
   2  * Copyright (c) 2016 Intel Corporation
   3  *
   4  * Permission to use, copy, modify, distribute, and sell this software and its
   5  * documentation for any purpose is hereby granted without fee, provided that
   6  * the above copyright notice appear in all copies and that both that copyright
   7  * notice and this permission notice appear in supporting documentation, and
   8  * that the name of the copyright holders not be used in advertising or
   9  * publicity pertaining to distribution of the software without specific,
  10  * written prior permission.  The copyright holders make no representations
  11  * about the suitability of this software for any purpose.  It is provided "as
  12  * is" without express or implied warranty.
  13  *
  14  * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  15  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  16  * EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  17  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  18  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  19  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  20  * OF THIS SOFTWARE.
  21  */
  22
  23 #include <linux/export.h>
  24 #include <drm/drmP.h>
  25 #include <drm/drm_property.h>
  26
  27 #include "drm_crtc_internal.h"
  28
  29 /**
  30  * DOC: overview
  31  *
  32  * Properties as represented by &drm_property are used to extend the modeset
  33  * interface exposed to userspace. For the atomic modeset IOCTL properties are
  34  * even the only way to transport metadata about the desired new modeset
  35  * configuration from userspace to the kernel. Properties have a well-defined
  36  * value range, which is enforced by the drm core. See the documentation of the
  37  * flags member of &struct drm_property for an overview of the different
  38  * property types and ranges.
  39  *
  40  * Properties don't store the current value directly, but need to be
  41  * instatiated by attaching them to a &drm_mode_object with
  42  * drm_object_attach_property().
  43  *
  44  * Property values are only 64bit. To support bigger piles of data (like gamma
  45  * tables, color correction matrices or large structures) a property can instead
  46  * point at a &drm_property_blob with that additional data.
  47  *
  48  * Properties are defined by their symbolic name, userspace must keep a
  49  * per-object mapping from those names to the property ID used in the atomic
  50  * IOCTL and in the get/set property IOCTL.
  51  */
  52
  53 static bool drm_property_type_valid(struct drm_property *property)
  54 {
  55         if (property->flags & DRM_MODE_PROP_EXTENDED_TYPE)
  56                 return !(property->flags & DRM_MODE_PROP_LEGACY_TYPE);
  57         return !!(property->flags & DRM_MODE_PROP_LEGACY_TYPE);
  58 }
  59
  60 /**
  61  * drm_property_create - create a new property type
  62  * @dev: drm device
  63  * @flags: flags specifying the property type
  64  * @name: name of the property
  65  * @num_values: number of pre-defined values
  66  *
  67  * This creates a new generic drm property which can then be attached to a drm
  68  * object with drm_object_attach_property(). The returned property object must
  69  * be freed with drm_property_destroy(), which is done automatically when
  70  * calling drm_mode_config_cleanup().
  71  *
  72  * Returns:
  73  * A pointer to the newly created property on success, NULL on failure.
  74  */
  75 struct drm_property *drm_property_create(struct drm_device *dev, int flags,
  76                                          const char *name, int num_values)
  77 {
  78         struct drm_property *property = NULL;
  79         int ret;
  80
  81         property = kzalloc(sizeof(struct drm_property), GFP_KERNEL);
  82         if (!property)
  83                 return NULL;
  84
  85         property->dev = dev;
  86
  87         if (num_values) {
  88                 property->values = kcalloc(num_values, sizeof(uint64_t),
  89                                            GFP_KERNEL);
  90                 if (!property->values)
  91                         goto fail;
  92         }
  93
  94         ret = drm_mode_object_add(dev, &property->base, DRM_MODE_OBJECT_PROPERTY);
  95         if (ret)
  96                 goto fail;
  97
  98         property->flags = flags;
  99         property->num_values = num_values;
 100         INIT_LIST_HEAD(&property->enum_list);
 101
 102         if (name) {
 103                 strncpy(property->name, name, DRM_PROP_NAME_LEN);
 104                 property->name[DRM_PROP_NAME_LEN-1] = '\0';
 105         }
 106
 107         list_add_tail(&property->head, &dev->mode_config.property_list);
 108
 109         WARN_ON(!drm_property_type_valid(property));
 110
 111         return property;
 112 fail:
 113         kfree(property->values);
 114         kfree(property);
 115         return NULL;
 116 }
 117 EXPORT_SYMBOL(drm_property_create);
 118
 119 /**
 120  * drm_property_create_enum - create a new enumeration property type
 121  * @dev: drm device
 122  * @flags: flags specifying the property type
 123  * @name: name of the property
 124  * @props: enumeration lists with property values
 125  * @num_values: number of pre-defined values
 126  *
 127  * This creates a new generic drm property which can then be attached to a drm
 128  * object with drm_object_attach_property(). The returned property object must
 129  * be freed with drm_property_destroy(), which is done automatically when
 130  * calling drm_mode_config_cleanup().
 131  *
 132  * Userspace is only allowed to set one of the predefined values for enumeration
 133  * properties.
 134  *
 135  * Returns:
 136  * A pointer to the newly created property on success, NULL on failure.
 137  */
 138 struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
 139                                          const char *name,
 140                                          const struct drm_prop_enum_list *props,
 141                                          int num_values)
 142 {
 143         struct drm_property *property;
 144         int i, ret;
 145
 146         flags |= DRM_MODE_PROP_ENUM;
 147
 148         property = drm_property_create(dev, flags, name, num_values);
 149         if (!property)
 150                 return NULL;
 151
 152         for (i = 0; i < num_values; i++) {
 153                 ret = drm_property_add_enum(property, i,
 154                                       props[i].type,
 155                                       props[i].name);
 156                 if (ret) {
 157                         drm_property_destroy(dev, property);
 158                         return NULL;
 159                 }
 160         }
 161
 162         return property;
 163 }
 164 EXPORT_SYMBOL(drm_property_create_enum);
 165
 166 /**
 167  * drm_property_create_bitmask - create a new bitmask property type
 168  * @dev: drm device
 169  * @flags: flags specifying the property type
 170  * @name: name of the property
 171  * @props: enumeration lists with property bitflags
 172  * @num_props: size of the @props array
 173  * @supported_bits: bitmask of all supported enumeration values
 174  *
 175  * This creates a new bitmask drm property which can then be attached to a drm
 176  * object with drm_object_attach_property(). The returned property object must
 177  * be freed with drm_property_destroy(), which is done automatically when
 178  * calling drm_mode_config_cleanup().
 179  *
 180  * Compared to plain enumeration properties userspace is allowed to set any
 181  * or'ed together combination of the predefined property bitflag values
 182  *
 183  * Returns:
 184  * A pointer to the newly created property on success, NULL on failure.
 185  */
 186 struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
 187                                          int flags, const char *name,
 188                                          const struct drm_prop_enum_list *props,
 189                                          int num_props,
 190                                          uint64_t supported_bits)
 191 {
 192         struct drm_property *property;
 193         int i, ret, index = 0;
 194         int num_values = hweight64(supported_bits);
 195
 196         flags |= DRM_MODE_PROP_BITMASK;
 197
 198         property = drm_property_create(dev, flags, name, num_values);
 199         if (!property)
 200                 return NULL;
 201         for (i = 0; i < num_props; i++) {
 202                 if (!(supported_bits & (1ULL << props[i].type)))
 203                         continue;
 204
 205                 if (WARN_ON(index >= num_values)) {
 206                         drm_property_destroy(dev, property);
 207                         return NULL;
 208                 }
 209
 210                 ret = drm_property_add_enum(property, index++,
 211                                       props[i].type,
 212                                       props[i].name);
 213                 if (ret) {
 214                         drm_property_destroy(dev, property);
 215                         return NULL;
 216                 }
 217         }
 218
 219         return property;
 220 }
 221 EXPORT_SYMBOL(drm_property_create_bitmask);
 222
 223 static struct drm_property *property_create_range(struct drm_device *dev,
 224                                          int flags, const char *name,
 225                                          uint64_t min, uint64_t max)
 226 {
 227         struct drm_property *property;
 228
 229         property = drm_property_create(dev, flags, name, 2);
 230         if (!property)
 231                 return NULL;
 232
 233         property->values[0] = min;
 234         property->values[1] = max;
 235
 236         return property;
 237 }
 238
 239 /**
 240  * drm_property_create_range - create a new unsigned ranged property type
 241  * @dev: drm device
 242  * @flags: flags specifying the property type
 243  * @name: name of the property
 244  * @min: minimum value of the property
 245  * @max: maximum value of the property
 246  *
 247  * This creates a new generic drm property which can then be attached to a drm
 248  * object with drm_object_attach_property(). The returned property object must
 249  * be freed with drm_property_destroy(), which is done automatically when
 250  * calling drm_mode_config_cleanup().
 251  *
 252  * Userspace is allowed to set any unsigned integer value in the (min, max)
 253  * range inclusive.
 254  *
 255  * Returns:
 256  * A pointer to the newly created property on success, NULL on failure.
 257  */
 258 struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
 259                                          const char *name,
 260                                          uint64_t min, uint64_t max)
 261 {
 262         return property_create_range(dev, DRM_MODE_PROP_RANGE | flags,
 263                         name, min, max);
 264 }
 265 EXPORT_SYMBOL(drm_property_create_range);
 266
 267 /**
 268  * drm_property_create_signed_range - create a new signed ranged property type
 269  * @dev: drm device
 270  * @flags: flags specifying the property type
 271  * @name: name of the property
 272  * @min: minimum value of the property
 273  * @max: maximum value of the property
 274  *
 275  * This creates a new generic drm property which can then be attached to a drm
 276  * object with drm_object_attach_property(). The returned property object must
 277  * be freed with drm_property_destroy(), which is done automatically when
 278  * calling drm_mode_config_cleanup().
 279  *
 280  * Userspace is allowed to set any signed integer value in the (min, max)
 281  * range inclusive.
 282  *
 283  * Returns:
 284  * A pointer to the newly created property on success, NULL on failure.
 285  */
 286 struct drm_property *drm_property_create_signed_range(struct drm_device *dev,
 287                                          int flags, const char *name,
 288                                          int64_t min, int64_t max)
 289 {
 290         return property_create_range(dev, DRM_MODE_PROP_SIGNED_RANGE | flags,
 291                         name, I642U64(min), I642U64(max));
 292 }
 293 EXPORT_SYMBOL(drm_property_create_signed_range);
 294
 295 /**
 296  * drm_property_create_object - create a new object property type
 297  * @dev: drm device
 298  * @flags: flags specifying the property type
 299  * @name: name of the property
 300  * @type: object type from DRM_MODE_OBJECT_* defines
 301  *
 302  * This creates a new generic drm property which can then be attached to a drm
 303  * object with drm_object_attach_property(). The returned property object must
 304  * be freed with drm_property_destroy(), which is done automatically when
 305  * calling drm_mode_config_cleanup().
 306  *
 307  * Userspace is only allowed to set this to any property value of the given
 308  * @type. Only useful for atomic properties, which is enforced.
 309  *
 310  * Returns:
 311  * A pointer to the newly created property on success, NULL on failure.
 312  */
 313 struct drm_property *drm_property_create_object(struct drm_device *dev,
 314                                                 int flags, const char *name,
 315                                                 uint32_t type)
 316 {
 317         struct drm_property *property;
 318
 319         flags |= DRM_MODE_PROP_OBJECT;
 320
 321         if (WARN_ON(!(flags & DRM_MODE_PROP_ATOMIC)))
 322                 return NULL;
 323
 324         property = drm_property_create(dev, flags, name, 1);
 325         if (!property)
 326                 return NULL;
 327
 328         property->values[0] = type;
 329
 330         return property;
 331 }
 332 EXPORT_SYMBOL(drm_property_create_object);
 333
 334 /**
 335  * drm_property_create_bool - create a new boolean property type
 336  * @dev: drm device
 337  * @flags: flags specifying the property type
 338  * @name: name of the property
 339  *
 340  * This creates a new generic drm property which can then be attached to a drm
 341  * object with drm_object_attach_property(). The returned property object must
 342  * be freed with drm_property_destroy(), which is done automatically when
 343  * calling drm_mode_config_cleanup().
 344  *
 345  * This is implemented as a ranged property with only {0, 1} as valid values.
 346  *
 347  * Returns:
 348  * A pointer to the newly created property on success, NULL on failure.
 349  */
 350 struct drm_property *drm_property_create_bool(struct drm_device *dev, int flags,
 351                                               const char *name)
 352 {
 353         return drm_property_create_range(dev, flags, name, 0, 1);
 354 }
 355 EXPORT_SYMBOL(drm_property_create_bool);
 356
 357 /**
 358  * drm_property_add_enum - add a possible value to an enumeration property
 359  * @property: enumeration property to change
 360  * @index: index of the new enumeration
 361  * @value: value of the new enumeration
 362  * @name: symbolic name of the new enumeration
 363  *
 364  * This functions adds enumerations to a property.
 365  *
 366  * It's use is deprecated, drivers should use one of the more specific helpers
 367  * to directly create the property with all enumerations already attached.
 368  *
 369  * Returns:
 370  * Zero on success, error code on failure.
 371  */
 372 int drm_property_add_enum(struct drm_property *property, int index,
 373                           uint64_t value, const char *name)
 374 {
 375         struct drm_property_enum *prop_enum;
 376
 377         if (!(drm_property_type_is(property, DRM_MODE_PROP_ENUM) ||
 378                         drm_property_type_is(property, DRM_MODE_PROP_BITMASK)))
 379                 return -EINVAL;
 380
 381         /*
 382          * Bitmask enum properties have the additional constraint of values
 383          * from 0 to 63
 384          */
 385         if (drm_property_type_is(property, DRM_MODE_PROP_BITMASK) &&
 386                         (value > 63))
 387                 return -EINVAL;
 388
 389         if (!list_empty(&property->enum_list)) {
 390                 list_for_each_entry(prop_enum, &property->enum_list, head) {
 391                         if (prop_enum->value == value) {
 392                                 strncpy(prop_enum->name, name, DRM_PROP_NAME_LEN);
 393                                 prop_enum->name[DRM_PROP_NAME_LEN-1] = '\0';
 394                                 return 0;
 395                         }
 396                 }
 397         }
 398
 399         prop_enum = kzalloc(sizeof(struct drm_property_enum), GFP_KERNEL);
 400         if (!prop_enum)
 401                 return -ENOMEM;
 402
 403         strncpy(prop_enum->name, name, DRM_PROP_NAME_LEN);
 404         prop_enum->name[DRM_PROP_NAME_LEN-1] = '\0';
 405         prop_enum->value = value;
 406
 407         property->values[index] = value;
 408         list_add_tail(&prop_enum->head, &property->enum_list);
 409         return 0;
 410 }
 411 EXPORT_SYMBOL(drm_property_add_enum);
 412
 413 /**
 414  * drm_property_destroy - destroy a drm property
 415  * @dev: drm device
 416  * @property: property to destry
 417  *
 418  * This function frees a property including any attached resources like
 419  * enumeration values.
 420  */
 421 void drm_property_destroy(struct drm_device *dev, struct drm_property *property)
 422 {
 423         struct drm_property_enum *prop_enum, *pt;
 424
 425         list_for_each_entry_safe(prop_enum, pt, &property->enum_list, head) {
 426                 list_del(&prop_enum->head);
 427                 kfree(prop_enum);
 428         }
 429
 430         if (property->num_values)
 431                 kfree(property->values);
 432         drm_mode_object_unregister(dev, &property->base);
 433         list_del(&property->head);
 434         kfree(property);
 435 }
 436 EXPORT_SYMBOL(drm_property_destroy);
 437
 438 int drm_mode_getproperty_ioctl(struct drm_device *dev,
 439                                void *data, struct drm_file *file_priv)
 440 {
 441         struct drm_mode_get_property *out_resp = data;
 442         struct drm_property *property;
 443         int enum_count = 0;
 444         int value_count = 0;
 445         int i, copied;
 446         struct drm_property_enum *prop_enum;
 447         struct drm_mode_property_enum __user *enum_ptr;
 448         uint64_t __user *values_ptr;
 449
 450         if (!drm_core_check_feature(dev, DRIVER_MODESET))
 451                 return -EINVAL;
 452
 453         property = drm_property_find(dev, out_resp->prop_id);
 454         if (!property)
 455                 return -ENOENT;
 456
 457         strncpy(out_resp->name, property->name, DRM_PROP_NAME_LEN);
 458         out_resp->name[DRM_PROP_NAME_LEN-1] = 0;
 459         out_resp->flags = property->flags;
 460
 461         value_count = property->num_values;
 462         values_ptr = u64_to_user_ptr(out_resp->values_ptr);
 463
 464         for (i = 0; i < value_count; i++) {
 465                 if (i < out_resp->count_values &&
 466                     put_user(property->values[i], values_ptr + i)) {
 467                         return -EFAULT;
 468                 }
 469         }
 470         out_resp->count_values = value_count;
 471
 472         copied = 0;
 473         enum_ptr = u64_to_user_ptr(out_resp->enum_blob_ptr);
 474
 475         if (drm_property_type_is(property, DRM_MODE_PROP_ENUM) ||
 476             drm_property_type_is(property, DRM_MODE_PROP_BITMASK)) {
 477                 list_for_each_entry(prop_enum, &property->enum_list, head) {
 478                         enum_count++;
 479                         if (out_resp->count_enum_blobs < enum_count)
 480                                 continue;
 481
 482                         if (copy_to_user(&enum_ptr[copied].value,
 483                                          &prop_enum->value, sizeof(uint64_t)))
 484                                 return -EFAULT;
 485
 486                         if (copy_to_user(&enum_ptr[copied].name,
 487                                          &prop_enum->name, DRM_PROP_NAME_LEN))
 488                                 return -EFAULT;
 489                         copied++;
 490                 }
 491                 out_resp->count_enum_blobs = enum_count;
 492         }
 493
 494         /*
 495          * NOTE: The idea seems to have been to use this to read all the blob
 496          * property values. But nothing ever added them to the corresponding
 497          * list, userspace always used the special-purpose get_blob ioctl to
 498          * read the value for a blob property. It also doesn't make a lot of
 499          * sense to return values here when everything else is just metadata for
 500          * the property itself.
 501          */
 502         if (drm_property_type_is(property, DRM_MODE_PROP_BLOB))
 503                 out_resp->count_enum_blobs = 0;
 504
 505         return 0;
 506 }
 507
 508 static void drm_property_free_blob(struct kref *kref)
 509 {
 510         struct drm_property_blob *blob =
 511                 container_of(kref, struct drm_property_blob, base.refcount);
 512
 513         mutex_lock(&blob->dev->mode_config.blob_lock);
 514         list_del(&blob->head_global);
 515         mutex_unlock(&blob->dev->mode_config.blob_lock);
 516
 517         drm_mode_object_unregister(blob->dev, &blob->base);
 518
 519         kfree(blob);
 520 }
 521
 522 /**
 523  * drm_property_create_blob - Create new blob property
 524  * @dev: DRM device to create property for
 525  * @length: Length to allocate for blob data
 526  * @data: If specified, copies data into blob
 527  *
 528  * Creates a new blob property for a specified DRM device, optionally
 529  * copying data. Note that blob properties are meant to be invariant, hence the
 530  * data must be filled out before the blob is used as the value of any property.
 531  *
 532  * Returns:
 533  * New blob property with a single reference on success, or an ERR_PTR
 534  * value on failure.
 535  */
 536 struct drm_property_blob *
 537 drm_property_create_blob(struct drm_device *dev, size_t length,
 538                          const void *data)
 539 {
 540         struct drm_property_blob *blob;
 541         int ret;
 542
 543         if (!length || length > ULONG_MAX - sizeof(struct drm_property_blob))
 544                 return ERR_PTR(-EINVAL);
 545
 546         blob = kzalloc(sizeof(struct drm_property_blob)+length, GFP_KERNEL);
 547         if (!blob)
 548                 return ERR_PTR(-ENOMEM);
 549
 550         /* This must be explicitly initialised, so we can safely call list_del
 551          * on it in the removal handler, even if it isn't in a file list. */
 552         INIT_LIST_HEAD(&blob->head_file);
 553         blob->length = length;
 554         blob->dev = dev;
 555
 556         if (data)
 557                 memcpy(blob->data, data, length);
 558
 559         ret = __drm_mode_object_add(dev, &blob->base, DRM_MODE_OBJECT_BLOB,
 560                                     true, drm_property_free_blob);
 561         if (ret) {
 562                 kfree(blob);
 563                 return ERR_PTR(-EINVAL);
 564         }
 565
 566         mutex_lock(&dev->mode_config.blob_lock);
 567         list_add_tail(&blob->head_global,
 568                       &dev->mode_config.property_blob_list);
 569         mutex_unlock(&dev->mode_config.blob_lock);
 570
 571         return blob;
 572 }
 573 EXPORT_SYMBOL(drm_property_create_blob);
 574
 575 /**
 576  * drm_property_blob_put - release a blob property reference
 577  * @blob: DRM blob property
 578  *
 579  * Releases a reference to a blob property. May free the object.
 580  */
 581 void drm_property_blob_put(struct drm_property_blob *blob)
 582 {
 583         if (!blob)
 584                 return;
 585
 586         drm_mode_object_put(&blob->base);
 587 }
 588 EXPORT_SYMBOL(drm_property_blob_put);
 589
 590 void drm_property_destroy_user_blobs(struct drm_device *dev,
 591                                      struct drm_file *file_priv)
 592 {
 593         struct drm_property_blob *blob, *bt;
 594
 595         /*
 596          * When the file gets released that means no one else can access the
 597          * blob list any more, so no need to grab dev->blob_lock.
 598          */
 599         list_for_each_entry_safe(blob, bt, &file_priv->blobs, head_file) {
 600                 list_del_init(&blob->head_file);
 601                 drm_property_blob_put(blob);
 602         }
 603 }
 604
 605 /**
 606  * drm_property_blob_get - acquire blob property reference
 607  * @blob: DRM blob property
 608  *
 609  * Acquires a reference to an existing blob property. Returns @blob, which
 610  * allows this to be used as a shorthand in assignments.
 611  */
 612 struct drm_property_blob *drm_property_blob_get(struct drm_property_blob *blob)
 613 {
 614         drm_mode_object_get(&blob->base);
 615         return blob;
 616 }
 617 EXPORT_SYMBOL(drm_property_blob_get);
 618
 619 /**
 620  * drm_property_lookup_blob - look up a blob property and take a reference
 621  * @dev: drm device
 622  * @id: id of the blob property
 623  *
 624  * If successful, this takes an additional reference to the blob property.
 625  * callers need to make sure to eventually unreference the returned property
 626  * again, using drm_property_blob_put().
 627  *
 628  * Return:
 629  * NULL on failure, pointer to the blob on success.
 630  */
 631 struct drm_property_blob *drm_property_lookup_blob(struct drm_device *dev,
 632                                                    uint32_t id)
 633 {
 634         struct drm_mode_object *obj;
 635         struct drm_property_blob *blob = NULL;
 636
 637         obj = __drm_mode_object_find(dev, id, DRM_MODE_OBJECT_BLOB);
 638         if (obj)
 639                 blob = obj_to_blob(obj);
 640         return blob;
 641 }
 642 EXPORT_SYMBOL(drm_property_lookup_blob);
 643
 644 /**
 645  * drm_property_replace_global_blob - replace existing blob property
 646  * @dev: drm device
 647  * @replace: location of blob property pointer to be replaced
 648  * @length: length of data for new blob, or 0 for no data
 649  * @data: content for new blob, or NULL for no data
 650  * @obj_holds_id: optional object for property holding blob ID
 651  * @prop_holds_id: optional property holding blob ID
 652  * @return 0 on success or error on failure
 653  *
 654  * This function will replace a global property in the blob list, optionally
 655  * updating a property which holds the ID of that property.
 656  *
 657  * If length is 0 or data is NULL, no new blob will be created, and the holding
 658  * property, if specified, will be set to 0.
 659  *
 660  * Access to the replace pointer is assumed to be protected by the caller, e.g.
 661  * by holding the relevant modesetting object lock for its parent.
 662  *
 663  * For example, a drm_connector has a 'PATH' property, which contains the ID
 664  * of a blob property with the value of the MST path information. Calling this
 665  * function with replace pointing to the connector's path_blob_ptr, length and
 666  * data set for the new path information, obj_holds_id set to the connector's
 667  * base object, and prop_holds_id set to the path property name, will perform
 668  * a completely atomic update. The access to path_blob_ptr is protected by the
 669  * caller holding a lock on the connector.
 670  */
 671 int drm_property_replace_global_blob(struct drm_device *dev,
 672                                      struct drm_property_blob **replace,
 673                                      size_t length,
 674                                      const void *data,
 675                                      struct drm_mode_object *obj_holds_id,
 676                                      struct drm_property *prop_holds_id)
 677 {
 678         struct drm_property_blob *new_blob = NULL;
 679         struct drm_property_blob *old_blob = NULL;
 680         int ret;
 681
 682         WARN_ON(replace == NULL);
 683
 684         old_blob = *replace;
 685
 686         if (length && data) {
 687                 new_blob = drm_property_create_blob(dev, length, data);
 688                 if (IS_ERR(new_blob))
 689                         return PTR_ERR(new_blob);
 690         }
 691
 692         if (obj_holds_id) {
 693                 ret = drm_object_property_set_value(obj_holds_id,
 694                                                     prop_holds_id,
 695                                                     new_blob ?
 696                                                         new_blob->base.id : 0);
 697                 if (ret != 0)
 698                         goto err_created;
 699         }
 700
 701         drm_property_blob_put(old_blob);
 702         *replace = new_blob;
 703
 704         return 0;
 705
 706 err_created:
 707         drm_property_blob_put(new_blob);
 708         return ret;
 709 }
 710 EXPORT_SYMBOL(drm_property_replace_global_blob);
 711
 712 /**
 713  * drm_property_replace_blob - replace a blob property
 714  * @blob: a pointer to the member blob to be replaced
 715  * @new_blob: the new blob to replace with
 716  *
 717  * Return: true if the blob was in fact replaced.
 718  */
 719 bool drm_property_replace_blob(struct drm_property_blob **blob,
 720                                struct drm_property_blob *new_blob)
 721 {
 722         struct drm_property_blob *old_blob = *blob;
 723
 724         if (old_blob == new_blob)
 725                 return false;
 726
 727         drm_property_blob_put(old_blob);
 728         if (new_blob)
 729                 drm_property_blob_get(new_blob);
 730         *blob = new_blob;
 731         return true;
 732 }
 733 EXPORT_SYMBOL(drm_property_replace_blob);
 734
 735 int drm_mode_getblob_ioctl(struct drm_device *dev,
 736                            void *data, struct drm_file *file_priv)
 737 {
 738         struct drm_mode_get_blob *out_resp = data;
 739         struct drm_property_blob *blob;
 740         int ret = 0;
 741
 742         if (!drm_core_check_feature(dev, DRIVER_MODESET))
 743                 return -EINVAL;
 744
 745         blob = drm_property_lookup_blob(dev, out_resp->blob_id);
 746         if (!blob)
 747                 return -ENOENT;
 748
 749         if (out_resp->length == blob->length) {
 750                 if (copy_to_user(u64_to_user_ptr(out_resp->data),
 751                                  blob->data,
 752                                  blob->length)) {
 753                         ret = -EFAULT;
 754                         goto unref;
 755                 }
 756         }
 757         out_resp->length = blob->length;
 758 unref:
 759         drm_property_blob_put(blob);
 760
 761         return ret;
 762 }
 763
 764 int drm_mode_createblob_ioctl(struct drm_device *dev,
 765                               void *data, struct drm_file *file_priv)
 766 {
 767         struct drm_mode_create_blob *out_resp = data;
 768         struct drm_property_blob *blob;
 769         int ret = 0;
 770
 771         if (!drm_core_check_feature(dev, DRIVER_MODESET))
 772                 return -EINVAL;
 773
 774         blob = drm_property_create_blob(dev, out_resp->length, NULL);
 775         if (IS_ERR(blob))
 776                 return PTR_ERR(blob);
 777
 778         if (copy_from_user(blob->data,
 779                            u64_to_user_ptr(out_resp->data),
 780                            out_resp->length)) {
 781                 ret = -EFAULT;
 782                 goto out_blob;
 783         }
 784
 785         /* Dropping the lock between create_blob and our access here is safe
 786          * as only the same file_priv can remove the blob; at this point, it is
 787          * not associated with any file_priv. */
 788         mutex_lock(&dev->mode_config.blob_lock);
 789         out_resp->blob_id = blob->base.id;
 790         list_add_tail(&blob->head_file, &file_priv->blobs);
 791         mutex_unlock(&dev->mode_config.blob_lock);
 792
 793         return 0;
 794
 795 out_blob:
 796         drm_property_blob_put(blob);
 797         return ret;
 798 }
 799
 800 int drm_mode_destroyblob_ioctl(struct drm_device *dev,
 801                                void *data, struct drm_file *file_priv)
 802 {
 803         struct drm_mode_destroy_blob *out_resp = data;
 804         struct drm_property_blob *blob = NULL, *bt;
 805         bool found = false;
 806         int ret = 0;
 807
 808         if (!drm_core_check_feature(dev, DRIVER_MODESET))
 809                 return -EINVAL;
 810
 811         blob = drm_property_lookup_blob(dev, out_resp->blob_id);
 812         if (!blob)
 813                 return -ENOENT;
 814
 815         mutex_lock(&dev->mode_config.blob_lock);
 816         /* Ensure the property was actually created by this user. */
 817         list_for_each_entry(bt, &file_priv->blobs, head_file) {
 818                 if (bt == blob) {
 819                         found = true;
 820                         break;
 821                 }
 822         }
 823
 824         if (!found) {
 825                 ret = -EPERM;
 826                 goto err;
 827         }
 828
 829         /* We must drop head_file here, because we may not be the last
 830          * reference on the blob. */
 831         list_del_init(&blob->head_file);
 832         mutex_unlock(&dev->mode_config.blob_lock);
 833
 834         /* One reference from lookup, and one from the filp. */
 835         drm_property_blob_put(blob);
 836         drm_property_blob_put(blob);
 837
 838         return 0;
 839
 840 err:
 841         mutex_unlock(&dev->mode_config.blob_lock);
 842         drm_property_blob_put(blob);
 843
 844         return ret;
 845 }
 846
 847 /* Some properties could refer to dynamic refcnt'd objects, or things that
 848  * need special locking to handle lifetime issues (ie. to ensure the prop
 849  * value doesn't become invalid part way through the property update due to
 850  * race).  The value returned by reference via 'obj' should be passed back
 851  * to drm_property_change_valid_put() after the property is set (and the
 852  * object to which the property is attached has a chance to take it's own
 853  * reference).
 854  */
 855 bool drm_property_change_valid_get(struct drm_property *property,
 856                                    uint64_t value, struct drm_mode_object **ref)
 857 {
 858         int i;
 859
 860         if (property->flags & DRM_MODE_PROP_IMMUTABLE)
 861                 return false;
 862
 863         *ref = NULL;
 864
 865         if (drm_property_type_is(property, DRM_MODE_PROP_RANGE)) {
 866                 if (value < property->values[0] || value > property->values[1])
 867                         return false;
 868                 return true;
 869         } else if (drm_property_type_is(property, DRM_MODE_PROP_SIGNED_RANGE)) {
 870                 int64_t svalue = U642I64(value);
 871
 872                 if (svalue < U642I64(property->values[0]) ||
 873                                 svalue > U642I64(property->values[1]))
 874                         return false;
 875                 return true;
 876         } else if (drm_property_type_is(property, DRM_MODE_PROP_BITMASK)) {
 877                 uint64_t valid_mask = 0;
 878
 879                 for (i = 0; i < property->num_values; i++)
 880                         valid_mask |= (1ULL << property->values[i]);
 881                 return !(value & ~valid_mask);
 882         } else if (drm_property_type_is(property, DRM_MODE_PROP_BLOB)) {
 883                 struct drm_property_blob *blob;
 884
 885                 if (value == 0)
 886                         return true;
 887
 888                 blob = drm_property_lookup_blob(property->dev, value);
 889                 if (blob) {
 890                         *ref = &blob->base;
 891                         return true;
 892                 } else {
 893                         return false;
 894                 }
 895         } else if (drm_property_type_is(property, DRM_MODE_PROP_OBJECT)) {
 896                 /* a zero value for an object property translates to null: */
 897                 if (value == 0)
 898                         return true;
 899
 900                 *ref = __drm_mode_object_find(property->dev, value,
 901                                               property->values[0]);
 902                 return *ref != NULL;
 903         }
 904
 905         for (i = 0; i < property->num_values; i++)
 906                 if (property->values[i] == value)
 907                         return true;
 908         return false;
 909 }
 910
 911 void drm_property_change_valid_put(struct drm_property *property,
 912                 struct drm_mode_object *ref)
 913 {
 914         if (!ref)
 915                 return;
 916
 917         if (drm_property_type_is(property, DRM_MODE_PROP_OBJECT)) {
 918                 drm_mode_object_put(ref);
 919         } else if (drm_property_type_is(property, DRM_MODE_PROP_BLOB))
 920                 drm_property_blob_put(obj_to_blob(ref));
 921 }