drivers/gpu/drm/drm_color_mgmt.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/uaccess.h>
  24
  25 #include <drm/drm_color_mgmt.h>
  26 #include <drm/drm_crtc.h>
  27 #include <drm/drm_device.h>
  28 #include <drm/drm_drv.h>
  29 #include <drm/drm_print.h>
  30
  31 #include "drm_crtc_internal.h"
  32
  33 /**
  34  * DOC: overview
  35  *
  36  * Color management or color space adjustments is supported through a set of 5
  37  * properties on the &drm_crtc object. They are set up by calling
  38  * drm_crtc_enable_color_mgmt().
  39  *
  40  * "DEGAMMA_LUT”:
  41  *      Blob property to set the degamma lookup table (LUT) mapping pixel data
  42  *      from the framebuffer before it is given to the transformation matrix.
  43  *      The data is interpreted as an array of &struct drm_color_lut elements.
  44  *      Hardware might choose not to use the full precision of the LUT elements
  45  *      nor use all the elements of the LUT (for example the hardware might
  46  *      choose to interpolate between LUT[0] and LUT[4]).
  47  *
  48  *      Setting this to NULL (blob property value set to 0) means a
  49  *      linear/pass-thru gamma table should be used. This is generally the
  50  *      driver boot-up state too. Drivers can access this blob through
  51  *      &drm_crtc_state.degamma_lut.
  52  *
  53  * “DEGAMMA_LUT_SIZE”:
  54  *      Unsinged range property to give the size of the lookup table to be set
  55  *      on the DEGAMMA_LUT property (the size depends on the underlying
  56  *      hardware). If drivers support multiple LUT sizes then they should
  57  *      publish the largest size, and sub-sample smaller sized LUTs (e.g. for
  58  *      split-gamma modes) appropriately.
  59  *
  60  * “CTM”:
  61  *      Blob property to set the current transformation matrix (CTM) apply to
  62  *      pixel data after the lookup through the degamma LUT and before the
  63  *      lookup through the gamma LUT. The data is interpreted as a struct
  64  *      &drm_color_ctm.
  65  *
  66  *      Setting this to NULL (blob property value set to 0) means a
  67  *      unit/pass-thru matrix should be used. This is generally the driver
  68  *      boot-up state too. Drivers can access the blob for the color conversion
  69  *      matrix through &drm_crtc_state.ctm.
  70  *
  71  * “GAMMA_LUT”:
  72  *      Blob property to set the gamma lookup table (LUT) mapping pixel data
  73  *      after the transformation matrix to data sent to the connector. The
  74  *      data is interpreted as an array of &struct drm_color_lut elements.
  75  *      Hardware might choose not to use the full precision of the LUT elements
  76  *      nor use all the elements of the LUT (for example the hardware might
  77  *      choose to interpolate between LUT[0] and LUT[4]).
  78  *
  79  *      Setting this to NULL (blob property value set to 0) means a
  80  *      linear/pass-thru gamma table should be used. This is generally the
  81  *      driver boot-up state too. Drivers can access this blob through
  82  *      &drm_crtc_state.gamma_lut.
  83  *
  84  * “GAMMA_LUT_SIZE”:
  85  *      Unsigned range property to give the size of the lookup table to be set
  86  *      on the GAMMA_LUT property (the size depends on the underlying hardware).
  87  *      If drivers support multiple LUT sizes then they should publish the
  88  *      largest size, and sub-sample smaller sized LUTs (e.g. for split-gamma
  89  *      modes) appropriately.
  90  *
  91  * There is also support for a legacy gamma table, which is set up by calling
  92  * drm_mode_crtc_set_gamma_size(). Drivers which support both should use
  93  * drm_atomic_helper_legacy_gamma_set() to alias the legacy gamma ramp with the
  94  * "GAMMA_LUT" property above.
  95  *
  96  * Support for different non RGB color encodings is controlled through
  97  * &drm_plane specific COLOR_ENCODING and COLOR_RANGE properties. They
  98  * are set up by calling drm_plane_create_color_properties().
  99  *
 100  * "COLOR_ENCODING"
 101  *      Optional plane enum property to support different non RGB
 102  *      color encodings. The driver can provide a subset of standard
 103  *      enum values supported by the DRM plane.
 104  *
 105  * "COLOR_RANGE"
 106  *      Optional plane enum property to support different non RGB
 107  *      color parameter ranges. The driver can provide a subset of
 108  *      standard enum values supported by the DRM plane.
 109  */
 110
 111 /**
 112  * drm_color_lut_extract - clamp and round LUT entries
 113  * @user_input: input value
 114  * @bit_precision: number of bits the hw LUT supports
 115  *
 116  * Extract a degamma/gamma LUT value provided by user (in the form of
 117  * &drm_color_lut entries) and round it to the precision supported by the
 118  * hardware.
 119  */
 120 uint32_t drm_color_lut_extract(uint32_t user_input, uint32_t bit_precision)
 121 {
 122         uint32_t val = user_input;
 123         uint32_t max = 0xffff >> (16 - bit_precision);
 124
 125         /* Round only if we're not using full precision. */
 126         if (bit_precision < 16) {
 127                 val += 1UL << (16 - bit_precision - 1);
 128                 val >>= 16 - bit_precision;
 129         }
 130
 131         return clamp_val(val, 0, max);
 132 }
 133 EXPORT_SYMBOL(drm_color_lut_extract);
 134
 135 /**
 136  * drm_crtc_enable_color_mgmt - enable color management properties
 137  * @crtc: DRM CRTC
 138  * @degamma_lut_size: the size of the degamma lut (before CSC)
 139  * @has_ctm: whether to attach ctm_property for CSC matrix
 140  * @gamma_lut_size: the size of the gamma lut (after CSC)
 141  *
 142  * This function lets the driver enable the color correction
 143  * properties on a CRTC. This includes 3 degamma, csc and gamma
 144  * properties that userspace can set and 2 size properties to inform
 145  * the userspace of the lut sizes. Each of the properties are
 146  * optional. The gamma and degamma properties are only attached if
 147  * their size is not 0 and ctm_property is only attached if has_ctm is
 148  * true.
 149  *
 150  * Drivers should use drm_atomic_helper_legacy_gamma_set() to implement the
 151  * legacy &drm_crtc_funcs.gamma_set callback.
 152  */
 153 void drm_crtc_enable_color_mgmt(struct drm_crtc *crtc,
 154                                 uint degamma_lut_size,
 155                                 bool has_ctm,
 156                                 uint gamma_lut_size)
 157 {
 158         struct drm_device *dev = crtc->dev;
 159         struct drm_mode_config *config = &dev->mode_config;
 160
 161         if (degamma_lut_size) {
 162                 drm_object_attach_property(&crtc->base,
 163                                            config->degamma_lut_property, 0);
 164                 drm_object_attach_property(&crtc->base,
 165                                            config->degamma_lut_size_property,
 166                                            degamma_lut_size);
 167         }
 168
 169         if (has_ctm)
 170                 drm_object_attach_property(&crtc->base,
 171                                            config->ctm_property, 0);
 172
 173         if (gamma_lut_size) {
 174                 drm_object_attach_property(&crtc->base,
 175                                            config->gamma_lut_property, 0);
 176                 drm_object_attach_property(&crtc->base,
 177                                            config->gamma_lut_size_property,
 178                                            gamma_lut_size);
 179         }
 180 }
 181 EXPORT_SYMBOL(drm_crtc_enable_color_mgmt);
 182
 183 /**
 184  * drm_mode_crtc_set_gamma_size - set the gamma table size
 185  * @crtc: CRTC to set the gamma table size for
 186  * @gamma_size: size of the gamma table
 187  *
 188  * Drivers which support gamma tables should set this to the supported gamma
 189  * table size when initializing the CRTC. Currently the drm core only supports a
 190  * fixed gamma table size.
 191  *
 192  * Returns:
 193  * Zero on success, negative errno on failure.
 194  */
 195 int drm_mode_crtc_set_gamma_size(struct drm_crtc *crtc,
 196                                  int gamma_size)
 197 {
 198         uint16_t *r_base, *g_base, *b_base;
 199         int i;
 200
 201         crtc->gamma_size = gamma_size;
 202
 203         crtc->gamma_store = kcalloc(gamma_size, sizeof(uint16_t) * 3,
 204                                     GFP_KERNEL);
 205         if (!crtc->gamma_store) {
 206                 crtc->gamma_size = 0;
 207                 return -ENOMEM;
 208         }
 209
 210         r_base = crtc->gamma_store;
 211         g_base = r_base + gamma_size;
 212         b_base = g_base + gamma_size;
 213         for (i = 0; i < gamma_size; i++) {
 214                 r_base[i] = i << 8;
 215                 g_base[i] = i << 8;
 216                 b_base[i] = i << 8;
 217         }
 218
 219
 220         return 0;
 221 }
 222 EXPORT_SYMBOL(drm_mode_crtc_set_gamma_size);
 223
 224 /**
 225  * drm_mode_gamma_set_ioctl - set the gamma table
 226  * @dev: DRM device
 227  * @data: ioctl data
 228  * @file_priv: DRM file info
 229  *
 230  * Set the gamma table of a CRTC to the one passed in by the user. Userspace can
 231  * inquire the required gamma table size through drm_mode_gamma_get_ioctl.
 232  *
 233  * Called by the user via ioctl.
 234  *
 235  * Returns:
 236  * Zero on success, negative errno on failure.
 237  */
 238 int drm_mode_gamma_set_ioctl(struct drm_device *dev,
 239                              void *data, struct drm_file *file_priv)
 240 {
 241         struct drm_mode_crtc_lut *crtc_lut = data;
 242         struct drm_crtc *crtc;
 243         void *r_base, *g_base, *b_base;
 244         int size;
 245         struct drm_modeset_acquire_ctx ctx;
 246         int ret = 0;
 247
 248         if (!drm_core_check_feature(dev, DRIVER_MODESET))
 249                 return -EOPNOTSUPP;
 250
 251         crtc = drm_crtc_find(dev, file_priv, crtc_lut->crtc_id);
 252         if (!crtc)
 253                 return -ENOENT;
 254
 255         if (crtc->funcs->gamma_set == NULL)
 256                 return -ENOSYS;
 257
 258         /* memcpy into gamma store */
 259         if (crtc_lut->gamma_size != crtc->gamma_size)
 260                 return -EINVAL;
 261
 262         DRM_MODESET_LOCK_ALL_BEGIN(dev, ctx, 0, ret);
 263
 264         size = crtc_lut->gamma_size * (sizeof(uint16_t));
 265         r_base = crtc->gamma_store;
 266         if (copy_from_user(r_base, (void __user *)(unsigned long)crtc_lut->red, size)) {
 267                 ret = -EFAULT;
 268                 goto out;
 269         }
 270
 271         g_base = r_base + size;
 272         if (copy_from_user(g_base, (void __user *)(unsigned long)crtc_lut->green, size)) {
 273                 ret = -EFAULT;
 274                 goto out;
 275         }
 276
 277         b_base = g_base + size;
 278         if (copy_from_user(b_base, (void __user *)(unsigned long)crtc_lut->blue, size)) {
 279                 ret = -EFAULT;
 280                 goto out;
 281         }
 282
 283         ret = crtc->funcs->gamma_set(crtc, r_base, g_base, b_base,
 284                                      crtc->gamma_size, &ctx);
 285
 286 out:
 287         DRM_MODESET_LOCK_ALL_END(ctx, ret);
 288         return ret;
 289
 290 }
 291
 292 /**
 293  * drm_mode_gamma_get_ioctl - get the gamma table
 294  * @dev: DRM device
 295  * @data: ioctl data
 296  * @file_priv: DRM file info
 297  *
 298  * Copy the current gamma table into the storage provided. This also provides
 299  * the gamma table size the driver expects, which can be used to size the
 300  * allocated storage.
 301  *
 302  * Called by the user via ioctl.
 303  *
 304  * Returns:
 305  * Zero on success, negative errno on failure.
 306  */
 307 int drm_mode_gamma_get_ioctl(struct drm_device *dev,
 308                              void *data, struct drm_file *file_priv)
 309 {
 310         struct drm_mode_crtc_lut *crtc_lut = data;
 311         struct drm_crtc *crtc;
 312         void *r_base, *g_base, *b_base;
 313         int size;
 314         int ret = 0;
 315
 316         if (!drm_core_check_feature(dev, DRIVER_MODESET))
 317                 return -EOPNOTSUPP;
 318
 319         crtc = drm_crtc_find(dev, file_priv, crtc_lut->crtc_id);
 320         if (!crtc)
 321                 return -ENOENT;
 322
 323         /* memcpy into gamma store */
 324         if (crtc_lut->gamma_size != crtc->gamma_size)
 325                 return -EINVAL;
 326
 327         drm_modeset_lock(&crtc->mutex, NULL);
 328         size = crtc_lut->gamma_size * (sizeof(uint16_t));
 329         r_base = crtc->gamma_store;
 330         if (copy_to_user((void __user *)(unsigned long)crtc_lut->red, r_base, size)) {
 331                 ret = -EFAULT;
 332                 goto out;
 333         }
 334
 335         g_base = r_base + size;
 336         if (copy_to_user((void __user *)(unsigned long)crtc_lut->green, g_base, size)) {
 337                 ret = -EFAULT;
 338                 goto out;
 339         }
 340
 341         b_base = g_base + size;
 342         if (copy_to_user((void __user *)(unsigned long)crtc_lut->blue, b_base, size)) {
 343                 ret = -EFAULT;
 344                 goto out;
 345         }
 346 out:
 347         drm_modeset_unlock(&crtc->mutex);
 348         return ret;
 349 }
 350
 351 static const char * const color_encoding_name[] = {
 352         [DRM_COLOR_YCBCR_BT601] = "ITU-R BT.601 YCbCr",
 353         [DRM_COLOR_YCBCR_BT709] = "ITU-R BT.709 YCbCr",
 354         [DRM_COLOR_YCBCR_BT2020] = "ITU-R BT.2020 YCbCr",
 355 };
 356
 357 static const char * const color_range_name[] = {
 358         [DRM_COLOR_YCBCR_FULL_RANGE] = "YCbCr full range",
 359         [DRM_COLOR_YCBCR_LIMITED_RANGE] = "YCbCr limited range",
 360 };
 361
 362 /**
 363  * drm_get_color_encoding_name - return a string for color encoding
 364  * @encoding: color encoding to compute name of
 365  *
 366  * In contrast to the other drm_get_*_name functions this one here returns a
 367  * const pointer and hence is threadsafe.
 368  */
 369 const char *drm_get_color_encoding_name(enum drm_color_encoding encoding)
 370 {
 371         if (WARN_ON(encoding >= ARRAY_SIZE(color_encoding_name)))
 372                 return "unknown";
 373
 374         return color_encoding_name[encoding];
 375 }
 376
 377 /**
 378  * drm_get_color_range_name - return a string for color range
 379  * @range: color range to compute name of
 380  *
 381  * In contrast to the other drm_get_*_name functions this one here returns a
 382  * const pointer and hence is threadsafe.
 383  */
 384 const char *drm_get_color_range_name(enum drm_color_range range)
 385 {
 386         if (WARN_ON(range >= ARRAY_SIZE(color_range_name)))
 387                 return "unknown";
 388
 389         return color_range_name[range];
 390 }
 391
 392 /**
 393  * drm_plane_create_color_properties - color encoding related plane properties
 394  * @plane: plane object
 395  * @supported_encodings: bitfield indicating supported color encodings
 396  * @supported_ranges: bitfileld indicating supported color ranges
 397  * @default_encoding: default color encoding
 398  * @default_range: default color range
 399  *
 400  * Create and attach plane specific COLOR_ENCODING and COLOR_RANGE
 401  * properties to @plane. The supported encodings and ranges should
 402  * be provided in supported_encodings and supported_ranges bitmasks.
 403  * Each bit set in the bitmask indicates that its number as enum
 404  * value is supported.
 405  */
 406 int drm_plane_create_color_properties(struct drm_plane *plane,
 407                                       u32 supported_encodings,
 408                                       u32 supported_ranges,
 409                                       enum drm_color_encoding default_encoding,
 410                                       enum drm_color_range default_range)
 411 {
 412         struct drm_device *dev = plane->dev;
 413         struct drm_property *prop;
 414         struct drm_prop_enum_list enum_list[max_t(int, DRM_COLOR_ENCODING_MAX,
 415                                                        DRM_COLOR_RANGE_MAX)];
 416         int i, len;
 417
 418         if (WARN_ON(supported_encodings == 0 ||
 419                     (supported_encodings & -BIT(DRM_COLOR_ENCODING_MAX)) != 0 ||
 420                     (supported_encodings & BIT(default_encoding)) == 0))
 421                 return -EINVAL;
 422
 423         if (WARN_ON(supported_ranges == 0 ||
 424                     (supported_ranges & -BIT(DRM_COLOR_RANGE_MAX)) != 0 ||
 425                     (supported_ranges & BIT(default_range)) == 0))
 426                 return -EINVAL;
 427
 428         len = 0;
 429         for (i = 0; i < DRM_COLOR_ENCODING_MAX; i++) {
 430                 if ((supported_encodings & BIT(i)) == 0)
 431                         continue;
 432
 433                 enum_list[len].type = i;
 434                 enum_list[len].name = color_encoding_name[i];
 435                 len++;
 436         }
 437
 438         prop = drm_property_create_enum(dev, 0, "COLOR_ENCODING",
 439                                         enum_list, len);
 440         if (!prop)
 441                 return -ENOMEM;
 442         plane->color_encoding_property = prop;
 443         drm_object_attach_property(&plane->base, prop, default_encoding);
 444         if (plane->state)
 445                 plane->state->color_encoding = default_encoding;
 446
 447         len = 0;
 448         for (i = 0; i < DRM_COLOR_RANGE_MAX; i++) {
 449                 if ((supported_ranges & BIT(i)) == 0)
 450                         continue;
 451
 452                 enum_list[len].type = i;
 453                 enum_list[len].name = color_range_name[i];
 454                 len++;
 455         }
 456
 457         prop = drm_property_create_enum(dev, 0, "COLOR_RANGE",
 458                                         enum_list, len);
 459         if (!prop)
 460                 return -ENOMEM;
 461         plane->color_range_property = prop;
 462         drm_object_attach_property(&plane->base, prop, default_range);
 463         if (plane->state)
 464                 plane->state->color_range = default_range;
 465
 466         return 0;
 467 }
 468 EXPORT_SYMBOL(drm_plane_create_color_properties);
 469
 470 /**
 471  * drm_color_lut_check - check validity of lookup table
 472  * @lut: property blob containing LUT to check
 473  * @tests: bitmask of tests to run
 474  *
 475  * Helper to check whether a userspace-provided lookup table is valid and
 476  * satisfies hardware requirements.  Drivers pass a bitmask indicating which of
 477  * the tests in &drm_color_lut_tests should be performed.
 478  *
 479  * Returns 0 on success, -EINVAL on failure.
 480  */
 481 int drm_color_lut_check(const struct drm_property_blob *lut, u32 tests)
 482 {
 483         const struct drm_color_lut *entry;
 484         int i;
 485
 486         if (!lut || !tests)
 487                 return 0;
 488
 489         entry = lut->data;
 490         for (i = 0; i < drm_color_lut_size(lut); i++) {
 491                 if (tests & DRM_COLOR_LUT_EQUAL_CHANNELS) {
 492                         if (entry[i].red != entry[i].blue ||
 493                             entry[i].red != entry[i].green) {
 494                                 DRM_DEBUG_KMS("All LUT entries must have equal r/g/b\n");
 495                                 return -EINVAL;
 496                         }
 497                 }
 498
 499                 if (i > 0 && tests & DRM_COLOR_LUT_NON_DECREASING) {
 500                         if (entry[i].red < entry[i - 1].red ||
 501                             entry[i].green < entry[i - 1].green ||
 502                             entry[i].blue < entry[i - 1].blue) {
 503                                 DRM_DEBUG_KMS("LUT entries must never decrease.\n");
 504                                 return -EINVAL;
 505                         }
 506                 }
 507         }
 508
 509         return 0;
 510 }
 511 EXPORT_SYMBOL(drm_color_lut_check);