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