2 * Copyright (c) 2016 Intel Corporation
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.
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
23 #include <linux/uaccess.h>
25 #include <drm/drm_atomic.h>
26 #include <drm/drm_color_mgmt.h>
27 #include <drm/drm_crtc.h>
28 #include <drm/drm_device.h>
29 #include <drm/drm_drv.h>
30 #include <drm/drm_print.h>
32 #include "drm_crtc_internal.h"
37 * Color management or color space adjustments is supported through a set of 5
38 * properties on the &drm_crtc object. They are set up by calling
39 * drm_crtc_enable_color_mgmt().
42 * Blob property to set the degamma lookup table (LUT) mapping pixel data
43 * from the framebuffer before it is given to the transformation matrix.
44 * The data is interpreted as an array of &struct drm_color_lut elements.
45 * Hardware might choose not to use the full precision of the LUT elements
46 * nor use all the elements of the LUT (for example the hardware might
47 * choose to interpolate between LUT[0] and LUT[4]).
49 * Setting this to NULL (blob property value set to 0) means a
50 * linear/pass-thru gamma table should be used. This is generally the
51 * driver boot-up state too. Drivers can access this blob through
52 * &drm_crtc_state.degamma_lut.
55 * Unsinged range property to give the size of the lookup table to be set
56 * on the DEGAMMA_LUT property (the size depends on the underlying
57 * hardware). If drivers support multiple LUT sizes then they should
58 * publish the largest size, and sub-sample smaller sized LUTs (e.g. for
59 * split-gamma modes) appropriately.
62 * Blob property to set the current transformation matrix (CTM) apply to
63 * pixel data after the lookup through the degamma LUT and before the
64 * lookup through the gamma LUT. The data is interpreted as a struct
67 * Setting this to NULL (blob property value set to 0) means a
68 * unit/pass-thru matrix should be used. This is generally the driver
69 * boot-up state too. Drivers can access the blob for the color conversion
70 * matrix through &drm_crtc_state.ctm.
73 * Blob property to set the gamma lookup table (LUT) mapping pixel data
74 * after the transformation matrix to data sent to the connector. The
75 * data is interpreted as an array of &struct drm_color_lut elements.
76 * Hardware might choose not to use the full precision of the LUT elements
77 * nor use all the elements of the LUT (for example the hardware might
78 * choose to interpolate between LUT[0] and LUT[4]).
80 * Setting this to NULL (blob property value set to 0) means a
81 * linear/pass-thru gamma table should be used. This is generally the
82 * driver boot-up state too. Drivers can access this blob through
83 * &drm_crtc_state.gamma_lut.
86 * Unsigned range property to give the size of the lookup table to be set
87 * on the GAMMA_LUT property (the size depends on the underlying hardware).
88 * If drivers support multiple LUT sizes then they should publish the
89 * largest size, and sub-sample smaller sized LUTs (e.g. for split-gamma
90 * modes) appropriately.
92 * There is also support for a legacy gamma table, which is set up by calling
93 * drm_mode_crtc_set_gamma_size(). The DRM core will then alias the legacy gamma
94 * ramp with "GAMMA_LUT" or, if that is unavailable, "DEGAMMA_LUT".
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().
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.
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.
112 * drm_color_ctm_s31_32_to_qm_n
114 * @user_input: input value
115 * @m: number of integer bits, only support m <= 32, include the sign-bit
116 * @n: number of fractional bits, only support n <= 32
118 * Convert and clamp S31.32 sign-magnitude to Qm.n (signed 2's complement).
119 * The sign-bit BIT(m+n-1) and above are 0 for positive value and 1 for negative
120 * the range of value is [-2^(m-1), 2^(m-1) - 2^-n]
123 * A Q3.12 format number:
124 * - required bit: 3 + 12 = 15bits
125 * - range: [-2^2, 2^2 - 2^−15]
127 * NOTE: the m can be zero if all bit_precision are used to present fractional
130 u64 drm_color_ctm_s31_32_to_qm_n(u64 user_input, u32 m, u32 n)
132 u64 mag = (user_input & ~BIT_ULL(63)) >> (32 - n);
133 bool negative = !!(user_input & BIT_ULL(63));
136 WARN_ON(m > 32 || n > 32);
138 val = clamp_val(mag, 0, negative ?
139 BIT_ULL(n + m - 1) : BIT_ULL(n + m - 1) - 1);
141 return negative ? -val : val;
143 EXPORT_SYMBOL(drm_color_ctm_s31_32_to_qm_n);
146 * drm_crtc_enable_color_mgmt - enable color management properties
148 * @degamma_lut_size: the size of the degamma lut (before CSC)
149 * @has_ctm: whether to attach ctm_property for CSC matrix
150 * @gamma_lut_size: the size of the gamma lut (after CSC)
152 * This function lets the driver enable the color correction
153 * properties on a CRTC. This includes 3 degamma, csc and gamma
154 * properties that userspace can set and 2 size properties to inform
155 * the userspace of the lut sizes. Each of the properties are
156 * optional. The gamma and degamma properties are only attached if
157 * their size is not 0 and ctm_property is only attached if has_ctm is
160 void drm_crtc_enable_color_mgmt(struct drm_crtc *crtc,
161 uint degamma_lut_size,
165 struct drm_device *dev = crtc->dev;
166 struct drm_mode_config *config = &dev->mode_config;
168 if (degamma_lut_size) {
169 drm_object_attach_property(&crtc->base,
170 config->degamma_lut_property, 0);
171 drm_object_attach_property(&crtc->base,
172 config->degamma_lut_size_property,
177 drm_object_attach_property(&crtc->base,
178 config->ctm_property, 0);
180 if (gamma_lut_size) {
181 drm_object_attach_property(&crtc->base,
182 config->gamma_lut_property, 0);
183 drm_object_attach_property(&crtc->base,
184 config->gamma_lut_size_property,
188 EXPORT_SYMBOL(drm_crtc_enable_color_mgmt);
191 * drm_mode_crtc_set_gamma_size - set the gamma table size
192 * @crtc: CRTC to set the gamma table size for
193 * @gamma_size: size of the gamma table
195 * Drivers which support gamma tables should set this to the supported gamma
196 * table size when initializing the CRTC. Currently the drm core only supports a
197 * fixed gamma table size.
200 * Zero on success, negative errno on failure.
202 int drm_mode_crtc_set_gamma_size(struct drm_crtc *crtc,
205 uint16_t *r_base, *g_base, *b_base;
208 crtc->gamma_size = gamma_size;
210 crtc->gamma_store = kcalloc(gamma_size, sizeof(uint16_t) * 3,
212 if (!crtc->gamma_store) {
213 crtc->gamma_size = 0;
217 r_base = crtc->gamma_store;
218 g_base = r_base + gamma_size;
219 b_base = g_base + gamma_size;
220 for (i = 0; i < gamma_size; i++) {
229 EXPORT_SYMBOL(drm_mode_crtc_set_gamma_size);
232 * drm_crtc_supports_legacy_gamma - does the crtc support legacy gamma correction table
235 * Returns true/false if the given crtc supports setting the legacy gamma
238 static bool drm_crtc_supports_legacy_gamma(struct drm_crtc *crtc)
240 u32 gamma_id = crtc->dev->mode_config.gamma_lut_property->base.id;
241 u32 degamma_id = crtc->dev->mode_config.degamma_lut_property->base.id;
243 if (!crtc->gamma_size)
246 if (crtc->funcs->gamma_set)
249 return !!(drm_mode_obj_find_prop_id(&crtc->base, gamma_id) ||
250 drm_mode_obj_find_prop_id(&crtc->base, degamma_id));
254 * drm_crtc_legacy_gamma_set - set the legacy gamma correction table
256 * @red: red correction table
257 * @green: green correction table
258 * @blue: green correction table
259 * @size: size of the tables
260 * @ctx: lock acquire context
262 * Implements support for legacy gamma correction table for drivers
263 * that have set drm_crtc_funcs.gamma_set or that support color management
264 * through the DEGAMMA_LUT/GAMMA_LUT properties. See
265 * drm_crtc_enable_color_mgmt() and the containing chapter for
266 * how the atomic color management and gamma tables work.
268 * This function sets the gamma using drm_crtc_funcs.gamma_set if set, or
269 * alternatively using crtc color management properties.
271 static int drm_crtc_legacy_gamma_set(struct drm_crtc *crtc,
272 u16 *red, u16 *green, u16 *blue,
274 struct drm_modeset_acquire_ctx *ctx)
276 struct drm_device *dev = crtc->dev;
277 struct drm_atomic_state *state;
278 struct drm_crtc_state *crtc_state;
279 struct drm_property_blob *blob;
280 struct drm_color_lut *blob_data;
281 u32 gamma_id = dev->mode_config.gamma_lut_property->base.id;
282 u32 degamma_id = dev->mode_config.degamma_lut_property->base.id;
287 if (crtc->funcs->gamma_set)
288 return crtc->funcs->gamma_set(crtc, red, green, blue, size, ctx);
290 if (drm_mode_obj_find_prop_id(&crtc->base, gamma_id))
291 use_gamma_lut = true;
292 else if (drm_mode_obj_find_prop_id(&crtc->base, degamma_id))
293 use_gamma_lut = false;
297 state = drm_atomic_state_alloc(crtc->dev);
301 blob = drm_property_create_blob(dev,
302 sizeof(struct drm_color_lut) * size,
310 /* Prepare GAMMA_LUT with the legacy values. */
311 blob_data = blob->data;
312 for (i = 0; i < size; i++) {
313 blob_data[i].red = red[i];
314 blob_data[i].green = green[i];
315 blob_data[i].blue = blue[i];
318 state->acquire_ctx = ctx;
319 crtc_state = drm_atomic_get_crtc_state(state, crtc);
320 if (IS_ERR(crtc_state)) {
321 ret = PTR_ERR(crtc_state);
325 /* Set GAMMA_LUT and reset DEGAMMA_LUT and CTM */
326 replaced = drm_property_replace_blob(&crtc_state->degamma_lut,
327 use_gamma_lut ? NULL : blob);
328 replaced |= drm_property_replace_blob(&crtc_state->ctm, NULL);
329 replaced |= drm_property_replace_blob(&crtc_state->gamma_lut,
330 use_gamma_lut ? blob : NULL);
331 crtc_state->color_mgmt_changed |= replaced;
333 ret = drm_atomic_commit(state);
336 drm_atomic_state_put(state);
337 drm_property_blob_put(blob);
342 * drm_mode_gamma_set_ioctl - set the gamma table
345 * @file_priv: DRM file info
347 * Set the gamma table of a CRTC to the one passed in by the user. Userspace can
348 * inquire the required gamma table size through drm_mode_gamma_get_ioctl.
350 * Called by the user via ioctl.
353 * Zero on success, negative errno on failure.
355 int drm_mode_gamma_set_ioctl(struct drm_device *dev,
356 void *data, struct drm_file *file_priv)
358 struct drm_mode_crtc_lut *crtc_lut = data;
359 struct drm_crtc *crtc;
360 void *r_base, *g_base, *b_base;
362 struct drm_modeset_acquire_ctx ctx;
365 if (!drm_core_check_feature(dev, DRIVER_MODESET))
368 crtc = drm_crtc_find(dev, file_priv, crtc_lut->crtc_id);
372 if (!drm_crtc_supports_legacy_gamma(crtc))
375 /* memcpy into gamma store */
376 if (crtc_lut->gamma_size != crtc->gamma_size)
379 DRM_MODESET_LOCK_ALL_BEGIN(dev, ctx, 0, ret);
381 size = crtc_lut->gamma_size * (sizeof(uint16_t));
382 r_base = crtc->gamma_store;
383 if (copy_from_user(r_base, (void __user *)(unsigned long)crtc_lut->red, size)) {
388 g_base = r_base + size;
389 if (copy_from_user(g_base, (void __user *)(unsigned long)crtc_lut->green, size)) {
394 b_base = g_base + size;
395 if (copy_from_user(b_base, (void __user *)(unsigned long)crtc_lut->blue, size)) {
400 ret = drm_crtc_legacy_gamma_set(crtc, r_base, g_base, b_base,
401 crtc->gamma_size, &ctx);
404 DRM_MODESET_LOCK_ALL_END(dev, ctx, ret);
410 * drm_mode_gamma_get_ioctl - get the gamma table
413 * @file_priv: DRM file info
415 * Copy the current gamma table into the storage provided. This also provides
416 * the gamma table size the driver expects, which can be used to size the
419 * Called by the user via ioctl.
422 * Zero on success, negative errno on failure.
424 int drm_mode_gamma_get_ioctl(struct drm_device *dev,
425 void *data, struct drm_file *file_priv)
427 struct drm_mode_crtc_lut *crtc_lut = data;
428 struct drm_crtc *crtc;
429 void *r_base, *g_base, *b_base;
433 if (!drm_core_check_feature(dev, DRIVER_MODESET))
436 crtc = drm_crtc_find(dev, file_priv, crtc_lut->crtc_id);
440 /* memcpy into gamma store */
441 if (crtc_lut->gamma_size != crtc->gamma_size)
444 drm_modeset_lock(&crtc->mutex, NULL);
445 size = crtc_lut->gamma_size * (sizeof(uint16_t));
446 r_base = crtc->gamma_store;
447 if (copy_to_user((void __user *)(unsigned long)crtc_lut->red, r_base, size)) {
452 g_base = r_base + size;
453 if (copy_to_user((void __user *)(unsigned long)crtc_lut->green, g_base, size)) {
458 b_base = g_base + size;
459 if (copy_to_user((void __user *)(unsigned long)crtc_lut->blue, b_base, size)) {
464 drm_modeset_unlock(&crtc->mutex);
468 static const char * const color_encoding_name[] = {
469 [DRM_COLOR_YCBCR_BT601] = "ITU-R BT.601 YCbCr",
470 [DRM_COLOR_YCBCR_BT709] = "ITU-R BT.709 YCbCr",
471 [DRM_COLOR_YCBCR_BT2020] = "ITU-R BT.2020 YCbCr",
474 static const char * const color_range_name[] = {
475 [DRM_COLOR_YCBCR_FULL_RANGE] = "YCbCr full range",
476 [DRM_COLOR_YCBCR_LIMITED_RANGE] = "YCbCr limited range",
480 * drm_get_color_encoding_name - return a string for color encoding
481 * @encoding: color encoding to compute name of
483 * In contrast to the other drm_get_*_name functions this one here returns a
484 * const pointer and hence is threadsafe.
486 const char *drm_get_color_encoding_name(enum drm_color_encoding encoding)
488 if (WARN_ON(encoding >= ARRAY_SIZE(color_encoding_name)))
491 return color_encoding_name[encoding];
495 * drm_get_color_range_name - return a string for color range
496 * @range: color range to compute name of
498 * In contrast to the other drm_get_*_name functions this one here returns a
499 * const pointer and hence is threadsafe.
501 const char *drm_get_color_range_name(enum drm_color_range range)
503 if (WARN_ON(range >= ARRAY_SIZE(color_range_name)))
506 return color_range_name[range];
510 * drm_plane_create_color_properties - color encoding related plane properties
511 * @plane: plane object
512 * @supported_encodings: bitfield indicating supported color encodings
513 * @supported_ranges: bitfileld indicating supported color ranges
514 * @default_encoding: default color encoding
515 * @default_range: default color range
517 * Create and attach plane specific COLOR_ENCODING and COLOR_RANGE
518 * properties to @plane. The supported encodings and ranges should
519 * be provided in supported_encodings and supported_ranges bitmasks.
520 * Each bit set in the bitmask indicates that its number as enum
521 * value is supported.
523 int drm_plane_create_color_properties(struct drm_plane *plane,
524 u32 supported_encodings,
525 u32 supported_ranges,
526 enum drm_color_encoding default_encoding,
527 enum drm_color_range default_range)
529 struct drm_device *dev = plane->dev;
530 struct drm_property *prop;
531 struct drm_prop_enum_list enum_list[max_t(int, DRM_COLOR_ENCODING_MAX,
532 DRM_COLOR_RANGE_MAX)];
535 if (WARN_ON(supported_encodings == 0 ||
536 (supported_encodings & -BIT(DRM_COLOR_ENCODING_MAX)) != 0 ||
537 (supported_encodings & BIT(default_encoding)) == 0))
540 if (WARN_ON(supported_ranges == 0 ||
541 (supported_ranges & -BIT(DRM_COLOR_RANGE_MAX)) != 0 ||
542 (supported_ranges & BIT(default_range)) == 0))
546 for (i = 0; i < DRM_COLOR_ENCODING_MAX; i++) {
547 if ((supported_encodings & BIT(i)) == 0)
550 enum_list[len].type = i;
551 enum_list[len].name = color_encoding_name[i];
555 prop = drm_property_create_enum(dev, 0, "COLOR_ENCODING",
559 plane->color_encoding_property = prop;
560 drm_object_attach_property(&plane->base, prop, default_encoding);
562 plane->state->color_encoding = default_encoding;
565 for (i = 0; i < DRM_COLOR_RANGE_MAX; i++) {
566 if ((supported_ranges & BIT(i)) == 0)
569 enum_list[len].type = i;
570 enum_list[len].name = color_range_name[i];
574 prop = drm_property_create_enum(dev, 0, "COLOR_RANGE",
578 plane->color_range_property = prop;
579 drm_object_attach_property(&plane->base, prop, default_range);
581 plane->state->color_range = default_range;
585 EXPORT_SYMBOL(drm_plane_create_color_properties);
588 * drm_color_lut_check - check validity of lookup table
589 * @lut: property blob containing LUT to check
590 * @tests: bitmask of tests to run
592 * Helper to check whether a userspace-provided lookup table is valid and
593 * satisfies hardware requirements. Drivers pass a bitmask indicating which of
594 * the tests in &drm_color_lut_tests should be performed.
596 * Returns 0 on success, -EINVAL on failure.
598 int drm_color_lut_check(const struct drm_property_blob *lut, u32 tests)
600 const struct drm_color_lut *entry;
607 for (i = 0; i < drm_color_lut_size(lut); i++) {
608 if (tests & DRM_COLOR_LUT_EQUAL_CHANNELS) {
609 if (entry[i].red != entry[i].blue ||
610 entry[i].red != entry[i].green) {
611 DRM_DEBUG_KMS("All LUT entries must have equal r/g/b\n");
616 if (i > 0 && tests & DRM_COLOR_LUT_NON_DECREASING) {
617 if (entry[i].red < entry[i - 1].red ||
618 entry[i].green < entry[i - 1].green ||
619 entry[i].blue < entry[i - 1].blue) {
620 DRM_DEBUG_KMS("LUT entries must never decrease.\n");
628 EXPORT_SYMBOL(drm_color_lut_check);