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 */
drm_color_ctm_s31_32_to_qm_n(u64 user_input,u32 m,u32 n)135 u64 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 }
148 EXPORT_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 */
drm_crtc_enable_color_mgmt(struct drm_crtc * crtc,uint degamma_lut_size,bool has_ctm,uint gamma_lut_size)168 void 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 }
196 EXPORT_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 */
drm_mode_crtc_set_gamma_size(struct drm_crtc * crtc,int gamma_size)210 int 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 }
237 EXPORT_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 */
drm_mode_gamma_set_ioctl(struct drm_device * dev,void * data,struct drm_file * file_priv)253 int 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
301 out:
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 */
drm_mode_gamma_get_ioctl(struct drm_device * dev,void * data,struct drm_file * file_priv)322 int 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 }
361 out:
362 drm_modeset_unlock(&crtc->mutex);
363 return ret;
364 }
365
366 static 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
372 static 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 */
drm_get_color_encoding_name(enum drm_color_encoding encoding)384 const 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 */
drm_get_color_range_name(enum drm_color_range range)399 const 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 */
drm_plane_create_color_properties(struct drm_plane * plane,u32 supported_encodings,u32 supported_ranges,enum drm_color_encoding default_encoding,enum drm_color_range default_range)421 int 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 }
483 EXPORT_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 */
drm_color_lut_check(const struct drm_property_blob * lut,u32 tests)496 int 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 }
526 EXPORT_SYMBOL(drm_color_lut_check);
527