@@ -473,12 +473,102 @@ FB_DAMAGE_CLIPS
Color Management Properties
---------------------------
+Below is how a typical hardware pipeline for color
+will look like:
+
+.. kernel-render:: DOT
+ :alt: Display Color Pipeline
+ :caption: Display Color Pipeline Overview
+
+ digraph "KMS" {
+ node [shape=box]
+
+ subgraph cluster_static {
+ style=dashed
+ label="Display Color Hardware Blocks"
+
+ node [bgcolor=grey style=filled]
+ "Plane Degamma A" -> "Plane CSC/CTM A"
+ "Plane CSC/CTM A" -> "Plane Gamma A"
+ "Pipe Blender" [color=lightblue,style=filled, width=5.25, height=0.75];
+ "Plane Gamma A" -> "Pipe Blender"
+ "Pipe Blender" -> "Pipe DeGamma"
+ "Pipe DeGamma" -> "Pipe CSC/CTM"
+ "Pipe CSC/CTM" -> "Pipe Gamma"
+ "Pipe Gamma" -> "Pipe Output"
+ }
+
+ subgraph cluster_static {
+ style=dashed
+
+ node [shape=box]
+ "Plane Degamma B" -> "Plane CSC/CTM B"
+ "Plane CSC/CTM B" -> "Plane Gamma B"
+ "Plane Gamma B" -> "Pipe Blender"
+ }
+
+ subgraph cluster_static {
+ style=dashed
+
+ node [shape=box]
+ "Plane Degamma C" -> "Plane CSC/CTM C"
+ "Plane CSC/CTM C" -> "Plane Gamma C"
+ "Plane Gamma C" -> "Pipe Blender"
+ }
+
+ subgraph cluster_fb {
+ style=dashed
+ label="RAM"
+
+ node [shape=box width=1.7 height=0.2]
+
+ "FB 1" -> "Plane Degamma A"
+ "FB 2" -> "Plane Degamma B"
+ "FB 3" -> "Plane Degamma C"
+ }
+ }
+
+In real world usecases,
+
+1. Plane Degamma can be used to linearize a non linear gamma
+encoded framebuffer. This is needed to do any linear math like
+color space conversion. For ex, linearize frames encoded in SRGB
+or by HDR curve.
+
+2. Later Plane CTM block can convert the content to some different
+colorspace. For ex, SRGB to BT2020 etc.
+
+3. Plane Gamma block can be used later to re-apply the non-linear
+curve. This can also be used to apply Tone Mapping for HDR usecases.
+
+All the layers or framebuffers need to be converted to same color
+space and format before blending. The plane color hardware blocks
+can help with this. Once the Data is blended, similar color processing
+can be done on blended output using pipe color hardware blocks.
+
+DRM Properties have been created to define and expose all these
+hardware blocks to userspace. A userspace application (compositor
+or any color app) can use these interfaces and define policies to
+efficiently use the display hardware for such color operations.
+
+Pipe Color Management Properties
+---------------------------------
+
.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
:doc: overview
.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
:export:
+Plane Color Management Properties
+---------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
+ :doc: Plane Color Properties
+
+.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
+ :doc: export
+
Tile Group Property
-------------------
@@ -655,6 +655,7 @@ static void drm_atomic_plane_print_state(struct drm_printer *p,
drm_get_color_encoding_name(state->color_encoding));
drm_printf(p, "\tcolor-range=%s\n",
drm_get_color_range_name(state->color_range));
+ drm_printf(p, "\tcolor_mgmt_changed=%d\n", state->color_mgmt_changed);
if (plane->funcs->atomic_print_state)
plane->funcs->atomic_print_state(p, state);
@@ -243,6 +243,10 @@ void __drm_atomic_helper_plane_duplicate_state(struct drm_plane *plane,
state->fence = NULL;
state->commit = NULL;
state->fb_damage_clips = NULL;
+
+ if (state->degamma_lut)
+ drm_property_blob_get(state->degamma_lut);
+ state->color_mgmt_changed = false;
}
EXPORT_SYMBOL(__drm_atomic_helper_plane_duplicate_state);
@@ -289,6 +293,7 @@ void __drm_atomic_helper_plane_destroy_state(struct drm_plane_state *state)
drm_crtc_commit_put(state->commit);
drm_property_blob_put(state->fb_damage_clips);
+ drm_property_blob_put(state->degamma_lut);
}
EXPORT_SYMBOL(__drm_atomic_helper_plane_destroy_state);
@@ -572,6 +572,13 @@ static int drm_atomic_plane_set_property(struct drm_plane *plane,
state->color_encoding = val;
} else if (property == plane->color_range_property) {
state->color_range = val;
+ } else if (property == plane->degamma_lut_property) {
+ ret = drm_atomic_replace_property_blob_from_id(dev,
+ &state->degamma_lut,
+ val, -1, sizeof(struct drm_color_lut),
+ &replaced);
+ state->color_mgmt_changed |= replaced;
+ return ret;
} else if (property == config->prop_fb_damage_clips) {
ret = drm_atomic_replace_property_blob_from_id(dev,
&state->fb_damage_clips,
@@ -635,6 +642,9 @@ static int drm_atomic_plane_set_property(struct drm_plane *plane,
*val = state->color_encoding;
} else if (property == plane->color_range_property) {
*val = state->color_range;
+ } else if (property == plane->degamma_lut_property) {
+ *val = (state->degamma_lut) ?
+ state->degamma_lut->base.id : 0;
} else if (property == config->prop_fb_damage_clips) {
*val = (state->fb_damage_clips) ?
state->fb_damage_clips->base.id : 0;
@@ -29,11 +29,11 @@
/**
* DOC: overview
*
- * Color management or color space adjustments is supported through a set of 5
- * properties on the &drm_crtc object. They are set up by calling
+ * Pipe Color management or color space adjustments is supported through a
+ * set of 5 properties on the &drm_crtc object. They are set up by calling
* drm_crtc_enable_color_mgmt().
*
- * "DEGAMMA_LUT”:
+ * "DEGAMMA_LUT
* Blob property to set the degamma lookup table (LUT) mapping pixel data
* from the framebuffer before it is given to the transformation matrix.
* The data is interpreted as an array of &struct drm_color_lut elements.
@@ -484,6 +484,43 @@ int drm_plane_create_color_properties(struct drm_plane *plane,
EXPORT_SYMBOL(drm_plane_create_color_properties);
/**
+ * DOC: Plane Color Properties
+ *
+ * Plane Color management or color space adjustments is supported
+ * through a set of 5 properties on the &drm_plane object.
+ *
+ * degamma_lut_property:
+ * Blob property which allows a userspace to provide LUT values
+ * to apply degamma curve using the h/w plane degamma processing
+ * engine, thereby making the content as linear for further color
+ * processing.
+ *
+ * degamma_lut_size_property:
+ * Range Property to indicate size of the plane degamma LUT.
+ */
+int drm_plane_color_create_prop(struct drm_device *dev,
+ struct drm_plane *plane)
+{
+ struct drm_property *prop;
+
+ prop = drm_property_create(dev, DRM_MODE_PROP_BLOB,
+ "PLANE_DEGAMMA_LUT", 0);
+ if (!prop)
+ return -ENOMEM;
+ plane->degamma_lut_property = prop;
+
+ prop = drm_property_create_range(dev, DRM_MODE_PROP_IMMUTABLE,
+ "PLANE_DEGAMMA_LUT_SIZE", 0,
+ UINT_MAX);
+ if (!prop)
+ return -ENOMEM;
+ plane->degamma_lut_size_property = prop;
+
+ return 0;
+}
+EXPORT_SYMBOL(drm_plane_color_create_prop);
+
+/**
* drm_color_lut_check - check validity of lookup table
* @lut: property blob containing LUT to check
* @tests: bitmask of tests to run
@@ -195,6 +195,14 @@ struct drm_plane_state {
*/
bool visible;
+ /* @degamma_lut:
+ *
+ * Lookup table for converting framebuffer pixel data before apply the
+ * color conversion matrix @ctm. See drm_plane_enable_color_mgmt(). The
+ * blob (if not NULL) is an array of &struct drm_color_lut_ext.
+ */
+ struct drm_property_blob *degamma_lut;
+
/**
* @commit: Tracks the pending commit to prevent use-after-free conditions,
* and for async plane updates.
@@ -205,6 +213,8 @@ struct drm_plane_state {
/** @state: backpointer to global drm_atomic_state */
struct drm_atomic_state *state;
+
+ u8 color_mgmt_changed : 1;
};
static inline struct drm_rect
@@ -705,6 +715,18 @@ struct drm_plane {
* See drm_plane_create_color_properties().
*/
struct drm_property *color_range_property;
+
+ /**
+ * @degamma_lut_property: Optional Plane property to set the LUT
+ * used to convert the framebuffer's colors to linear gamma.
+ */
+ struct drm_property *degamma_lut_property;
+
+ /**
+ * @degamma_lut_size_property: Optional Plane property for the
+ * size of the degamma LUT as supported by the driver (read-only).
+ */
+ struct drm_property *degamma_lut_size_property;
};
#define obj_to_plane(x) container_of(x, struct drm_plane, base)
@@ -754,6 +776,8 @@ static inline u32 drm_plane_mask(const struct drm_plane *plane)
int drm_mode_plane_set_obj_prop(struct drm_plane *plane,
struct drm_property *property,
uint64_t value);
+int drm_plane_color_create_prop(struct drm_device *dev,
+ struct drm_plane *plane);
/**
* drm_plane_find - find a &drm_plane