[v2 0/3] Document fixes for DRM UAPI and HDR

[v2 0/3] Document fixes for DRM UAPI and HDR

[Uma Shankar]

This series adds DRM UAPI header structure documentation to kernel
docs. Fixes issues with existing structure documentation in drm
uapi header.

This also fixes warnings in HDR doc and addresses suggestions from
Daniel Vetter.

v2: 2 patches from v1 are merged. This series version adds remaining
on top of that. Addressed review comments from Daniel Vetter.

Uma Shankar (3):
  drm: ADD UAPI structure definition section in kernel doc
  drm: Fix docbook warnings in hdr metadata helper structures
  video/hdmi: Dropped static functions from kernel doc

 Documentation/gpu/drm-uapi.rst  |  9 +++++
 drivers/gpu/drm/drm_connector.c | 37 +++++++++++++++++++++
 drivers/video/hdmi.c            | 30 -----------------
 include/drm/drm_connector.h     |  1 +
 include/drm/drm_mode_config.h   |  4 +--
 include/linux/hdmi.h            | 12 +++++++
 include/uapi/drm/drm_mode.h     | 74 ++++++++++++++++++++++++++++++++++++++++-
 7 files changed, 134 insertions(+), 33 deletions(-)

-- 
1.9.1

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[v2 1/3] drm: ADD UAPI structure definition section in kernel doc

[Uma Shankar]

Add a new section for UAPI structure and helper definitions
in kernel docbook.

Suggested-by: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Uma Shankar <uma.shankar@intel.com>
---
 Documentation/gpu/drm-uapi.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index f368e58..94f9052 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -329,3 +329,12 @@ DRM_IOCTL_MODESET_CTL
     mode setting, since on many devices the vertical blank counter is
     reset to 0 at some point during modeset. Modern drivers should not
     call this any more since with kernel mode setting it is a no-op.
+
+Userspace API Structures
+========================
+
+.. kernel-doc:: include/uapi/drm/drm_mode.h
+   :doc: overview
+
+.. kernel-doc:: include/uapi/drm/drm_mode.h
+   :internal:
-- 
1.9.1

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[v2 2/3] drm: Fix docbook warnings in hdr metadata helper structures

[Uma Shankar]

Fixes the following warnings:
./include/drm/drm_mode_config.h:841: warning: Incorrect use of
kernel-doc format:          * hdr_output_metadata_property: Connector
property containing hdr
./include/drm/drm_mode_config.h:918: warning: Function parameter or member 'hdr_output_metadata_property' not described in 'drm_mode_config'
./include/drm/drm_connector.h:1251: warning: Function parameter or member 'hdr_output_metadata' not described in 'drm_connector'
./include/drm/drm_connector.h:1251: warning: Function parameter or member 'hdr_sink_metadata' not described in 'drm_connector'

Also adds some property documentation for HDR Metadata Connector
Property in connector property create function.

v2: Fixed Sean Paul's review comments.

v3: Fixed Daniel Vetter's review comments, added the UAPI structure
definition section in kernel docs.

v4: Fixed Daniel Vetter's review comments.

Cc: Shashank Sharma <shashank.sharma@intel.com>
Cc: Ville Syrjä <ville.syrjala@linux.intel.com>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <maxime.ripard@bootlin.com>
Cc: Sean Paul <sean@poorly.run>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Bartlomiej Zolnierkiewicz <b.zolnierkie@samsung.com>
Cc: "Ville Syrjä" <ville.syrjala@linux.intel.com>
Cc: Hans Verkuil <hansverk@cisco.com>
Cc: dri-devel@lists.freedesktop.org
Cc: linux-fbdev@vger.kernel.org
Reviewed-by: Sean Paul <sean@poorly.run>
Signed-off-by: Uma Shankar <uma.shankar@intel.com>
---
 drivers/gpu/drm/drm_connector.c | 37 +++++++++++++++++++++
 include/drm/drm_connector.h     |  1 +
 include/drm/drm_mode_config.h   |  4 +--
 include/linux/hdmi.h            | 12 +++++++
 include/uapi/drm/drm_mode.h     | 74 ++++++++++++++++++++++++++++++++++++++++-
 5 files changed, 125 insertions(+), 3 deletions(-)

diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
index c9ac8b9..c445d57 100644
--- a/drivers/gpu/drm/drm_connector.c
+++ b/drivers/gpu/drm/drm_connector.c
@@ -956,6 +956,43 @@ int drm_display_info_set_bus_formats(struct drm_display_info *info,
  *	  is no longer protected and userspace should take appropriate action
  *	  (whatever that might be).
  *
+ * HDR_OUTPUT_METADATA:
+ *	Connector property to enable userspace to send HDR Metadata to
+ *	driver. This metadata is based on the composition and blending
+ *	policies decided by user, taking into account the hardware and
+ *	sink capabilities. The driver gets this metadata and creates a
+ *	Dynamic Range and Mastering Infoframe (DRM) in case of HDMI,
+ *	SDP packet (Non-audio INFOFRAME SDP v1.3) for DP. This is then
+ *	sent to sink. This notifies the sink of the upcoming frame's Color
+ *	Encoding and Luminance parameters.
+ *
+ *	Userspace first need to detect the HDR capabilities of sink by
+ *	reading and parsing the EDID. Details of HDR metadata for HDMI
+ *	are added in CTA 861.G spec. For DP , its defined in VESA DP
+ *	Standard v1.4. It needs to then get the metadata information
+ *	of the video/game/app content which are encoded in HDR (basically
+ *	using HDR transfer functions). With this information it needs to
+ *	decide on a blending policy and compose the relevant
+ *	layers/overlays into a common format. Once this blending is done,
+ *	userspace will be aware of the metadata of the composed frame to
+ *	be send to sink. It then uses this property to communicate this
+ *	metadata to driver which then make a Infoframe packet and sends
+ *	to sink based on the type of encoder connected.
+ *
+ *	Userspace will be responsible to do Tone mapping operation in case:
+ *		- Some layers are HDR and others are SDR
+ *		- HDR layers luminance is not same as sink
+ *	It will even need to do colorspace conversion and get all layers
+ *	to one common colorspace for blending. It can use either GL, Media
+ *	or display engine to get this done based on the capabilties of the
+ *	associated hardware.
+ *
+ *	Driver expects metadata to be put in &hdr_output_metadata structure
+ *	from userspace. It parses EDID and saves the sink metadata in
+ *	&hdr_sink_metadata. Driver uses &drm_hdmi_infoframe_set_hdr_metadata
+ *	helper to set the HDR metadata, &hdmi_drm_infoframe_pack to pack the
+ *	infoframe as per spec, in case of HDMI encoder.
+ *
  * max bpc:
  *	This range property is used by userspace to limit the bit depth. When
  *	used the driver would limit the bpc in accordance with the valid range
diff --git a/include/drm/drm_connector.h b/include/drm/drm_connector.h
index 5476561..47e749b 100644
--- a/include/drm/drm_connector.h
+++ b/include/drm/drm_connector.h
@@ -1244,6 +1244,7 @@ struct drm_connector {
 	 */
 	struct llist_node free_node;
 
+	/** @hdr_sink_metadata: HDR Metadata Information read from sink */
 	struct hdr_sink_metadata hdr_sink_metadata;
 };
 
diff --git a/include/drm/drm_mode_config.h b/include/drm/drm_mode_config.h
index 4f88cc9..759d462 100644
--- a/include/drm/drm_mode_config.h
+++ b/include/drm/drm_mode_config.h
@@ -837,8 +837,8 @@ struct drm_mode_config {
 	struct drm_property *writeback_out_fence_ptr_property;
 
 	/**
-	 * hdr_output_metadata_property: Connector property containing hdr
-	 * metatda. This will be provided by userspace compositors based
+	 * @hdr_output_metadata_property: Connector property containing hdr
+	 * metatada. This will be provided by userspace compositors based
 	 * on HDR content
 	 */
 	struct drm_property *hdr_output_metadata_property;
diff --git a/include/linux/hdmi.h b/include/linux/hdmi.h
index ee55ba5..9918a6c 100644
--- a/include/linux/hdmi.h
+++ b/include/linux/hdmi.h
@@ -367,8 +367,19 @@ struct hdr_static_metadata {
 	__u16 min_cll;
 };
 
+/**
+ * struct hdr_sink_metadata - HDR sink metadata
+ *
+ * Metadata Information read from Sink's EDID
+ */
 struct hdr_sink_metadata {
+	/**
+	 * @metadata_type: Static_Metadata_Descriptor_ID.
+	 */
 	__u32 metadata_type;
+	/**
+	 * @hdmi_type1: HDR Metadata Infoframe.
+	 */
 	union {
 		struct hdr_static_metadata hdmi_type1;
 	};
@@ -398,6 +409,7 @@ ssize_t hdmi_vendor_infoframe_pack_only(const struct hdmi_vendor_infoframe *fram
  * @spd: spd infoframe
  * @vendor: union of all vendor infoframes
  * @audio: audio infoframe
+ * @drm: Dynamic Range and Mastering infoframe
  *
  * This is used by the generic pack function. This works since all infoframes
  * have the same header which also indicates which type of infoframe should be
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index 19b5cf3..5ab331e 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -33,6 +33,15 @@
 extern "C" {
 #endif
 
+/**
+ * DOC: overview
+ *
+ * DRM exposes many UAPI and structure definition to have a consistent
+ * and standardized interface with user.
+ * Userspace can refer to these structure definitions and UAPI formats
+ * to communicate to driver
+ */
+
 #define DRM_CONNECTOR_NAME_LEN	32
 #define DRM_DISPLAY_MODE_LEN	32
 #define DRM_PROP_NAME_LEN	32
@@ -630,24 +639,87 @@ struct drm_color_lut {
 	__u16 reserved;
 };
 
-/* HDR Metadata Infoframe as per 861.G spec */
+/**
+ * struct hdr_metadata_infoframe - HDR Metadata Infoframe Data.
+ *
+ * HDR Metadata Infoframe as per CTA 861.G spec. This is expected
+ * to match exactly with the spec.
+ *
+ * Userspace is expected to pass the metadata information as per
+ * the format described in this structure.
+ */
 struct hdr_metadata_infoframe {
+	/**
+	 * @eotf: Electro-Optical Transfer Function (EOTF)
+	 * used in the stream.
+	 */
 	__u8 eotf;
+	/**
+	 * @metadata_type: Static_Metadata_Descriptor_ID.
+	 */
 	__u8 metadata_type;
+	/**
+	 * @display_primaries: Color Primaries of the Data.
+	 * These are coded as unsigned 16-bit values in units of
+	 * 0.00002, where 0x0000 represents zero and 0xC350
+	 * represents 1.0000.
+	 * @display_primaries.x: X cordinate of color primary.
+	 * @display_primaries.y: Y cordinate of color primary.
+	 */
 	struct {
 		__u16 x, y;
 		} display_primaries[3];
+	/**
+	 * @white_point: White Point of Colorspace Data.
+	 * These are coded as unsigned 16-bit values in units of
+	 * 0.00002, where 0x0000 represents zero and 0xC350
+	 * represents 1.0000.
+	 * @white_point.x: X cordinate of whitepoint of color primary.
+	 * @white_point.y: Y cordinate of whitepoint of color primary.
+	 */
 	struct {
 		__u16 x, y;
 		} white_point;
+	/**
+	 * @max_display_mastering_luminance: Max Mastering Display Luminance.
+	 * This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
+	 * where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
+	 */
 	__u16 max_display_mastering_luminance;
+	/**
+	 * @min_display_mastering_luminance: Min Mastering Display Luminance.
+	 * This value is coded as an unsigned 16-bit value in units of
+	 * 0.0001 cd/m2, where 0x0001 represents 0.0001 cd/m2 and 0xFFFF
+	 * represents 6.5535 cd/m2.
+	 */
 	__u16 min_display_mastering_luminance;
+	/**
+	 * @max_cll: Max Content Light Level.
+	 * This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
+	 * where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
+	 */
 	__u16 max_cll;
+	/**
+	 * @max_fall: Max Frame Average Light Level.
+	 * This value is coded as an unsigned 16-bit value in units of 1 cd/m2,
+	 * where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2.
+	 */
 	__u16 max_fall;
 };
 
+/**
+ * struct hdr_output_metadata - HDR output metadata
+ *
+ * Metadata Information to be passed from userspace
+ */
 struct hdr_output_metadata {
+	/**
+	 * @metadata_type: Static_Metadata_Descriptor_ID.
+	 */
 	__u32 metadata_type;
+	/**
+	 * @hdmi_metadata_type1: HDR Metadata Infoframe.
+	 */
 	union {
 		struct hdr_metadata_infoframe hdmi_metadata_type1;
 	};
-- 
1.9.1

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

[v2 3/3] video/hdmi: Dropped static functions from kernel doc

[Uma Shankar]

Dropped static functions from kernel documentation.

v2: Dropped the comments altogether for static functions,
as the definitions seems self explanatory.

Suggested-by: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Uma Shankar <uma.shankar@intel.com>
---
 drivers/video/hdmi.c | 30 ------------------------------
 1 file changed, 30 deletions(-)

diff --git a/drivers/video/hdmi.c b/drivers/video/hdmi.c
index b99ba01..b939bc2 100644
--- a/drivers/video/hdmi.c
+++ b/drivers/video/hdmi.c
@@ -1191,12 +1191,6 @@ static const char *hdmi_nups_get_name(enum hdmi_nups nups)
 	return "Invalid";
 }
 
-/**
- * hdmi_avi_infoframe_log() - log info of HDMI AVI infoframe
- * @level: logging level
- * @dev: device
- * @frame: HDMI AVI infoframe
- */
 static void hdmi_avi_infoframe_log(const char *level,
 				   struct device *dev,
 				   const struct hdmi_avi_infoframe *frame)
@@ -1268,12 +1262,6 @@ static const char *hdmi_spd_sdi_get_name(enum hdmi_spd_sdi sdi)
 	return "Reserved";
 }
 
-/**
- * hdmi_spd_infoframe_log() - log info of HDMI SPD infoframe
- * @level: logging level
- * @dev: device
- * @frame: HDMI SPD infoframe
- */
 static void hdmi_spd_infoframe_log(const char *level,
 				   struct device *dev,
 				   const struct hdmi_spd_infoframe *frame)
@@ -1404,12 +1392,6 @@ static void hdmi_spd_infoframe_log(const char *level,
 	return "Reserved";
 }
 
-/**
- * hdmi_audio_infoframe_log() - log info of HDMI AUDIO infoframe
- * @level: logging level
- * @dev: device
- * @frame: HDMI AUDIO infoframe
- */
 static void hdmi_audio_infoframe_log(const char *level,
 				     struct device *dev,
 				     const struct hdmi_audio_infoframe *frame)
@@ -1437,12 +1419,6 @@ static void hdmi_audio_infoframe_log(const char *level,
 			frame->downmix_inhibit ? "Yes" : "No");
 }
 
-/**
- * hdmi_drm_infoframe_log() - log info of HDMI DRM infoframe
- * @level: logging level
- * @dev: device
- * @frame: HDMI DRM infoframe
- */
 static void hdmi_drm_infoframe_log(const char *level,
 				   struct device *dev,
 				   const struct hdmi_drm_infoframe *frame)
@@ -1500,12 +1476,6 @@ static void hdmi_drm_infoframe_log(const char *level,
 	return "Reserved";
 }
 
-/**
- * hdmi_vendor_infoframe_log() - log info of HDMI VENDOR infoframe
- * @level: logging level
- * @dev: device
- * @frame: HDMI VENDOR infoframe
- */
 static void
 hdmi_vendor_any_infoframe_log(const char *level,
 			      struct device *dev,
-- 
1.9.1

_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

✗ Fi.CI.BAT: failure for Document fixes for DRM UAPI and HDR (rev2)

[Patchwork]

== Series Details ==

Series: Document fixes for DRM UAPI and HDR (rev2)
URL   : https://patchwork.freedesktop.org/series/61349/
State : failure

== Summary ==

CI Bug Log - changes from CI_DRM_6180 -> Patchwork_13157
====================================================

Summary
-------

  **FAILURE**

  Serious unknown changes coming with Patchwork_13157 absolutely need to be
  verified manually.
  
  If you think the reported changes have nothing to do with the changes
  introduced in Patchwork_13157, please notify your bug team to allow them
  to document this new failure mode, which will reduce false positives in CI.

  External URL: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_13157/

Possible new issues
-------------------

  Here are the unknown changes that may have been introduced in Patchwork_13157:

### IGT changes ###

#### Possible regressions ####

  * igt@i915_selftest@live_evict:
    - fi-bsw-n3050:       [PASS][1] -> [INCOMPLETE][2]
   [1]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_6180/fi-bsw-n3050/igt@i915_selftest@live_evict.html
   [2]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_13157/fi-bsw-n3050/igt@i915_selftest@live_evict.html

  
Known issues
------------

  Here are the changes found in Patchwork_13157 that come from known issues:

### IGT changes ###

#### Issues hit ####

  * igt@gem_basic@create-close:
    - fi-icl-u3:          [PASS][3] -> [DMESG-WARN][4] ([fdo#107724])
   [3]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_6180/fi-icl-u3/igt@gem_basic@create-close.html
   [4]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_13157/fi-icl-u3/igt@gem_basic@create-close.html

  
#### Possible fixes ####

  * igt@gem_exec_reloc@basic-write-gtt-noreloc:
    - fi-icl-u3:          [DMESG-WARN][5] ([fdo#107724]) -> [PASS][6]
   [5]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_6180/fi-icl-u3/igt@gem_exec_reloc@basic-write-gtt-noreloc.html
   [6]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_13157/fi-icl-u3/igt@gem_exec_reloc@basic-write-gtt-noreloc.html

  * igt@gem_exec_suspend@basic-s3:
    - fi-blb-e6850:       [INCOMPLETE][7] ([fdo#107718]) -> [PASS][8]
   [7]: https://intel-gfx-ci.01.org/tree/drm-tip/CI_DRM_6180/fi-blb-e6850/igt@gem_exec_suspend@basic-s3.html
   [8]: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_13157/fi-blb-e6850/igt@gem_exec_suspend@basic-s3.html

  
  {name}: This element is suppressed. This means it is ignored when computing
          the status of the difference (SUCCESS, WARNING, or FAILURE).

  [fdo#107713]: https://bugs.freedesktop.org/show_bug.cgi?id=107713
  [fdo#107718]: https://bugs.freedesktop.org/show_bug.cgi?id=107718
  [fdo#107724]: https://bugs.freedesktop.org/show_bug.cgi?id=107724
  [fdo#109100]: https://bugs.freedesktop.org/show_bug.cgi?id=109100
  [fdo#109673]: https://bugs.freedesktop.org/show_bug.cgi?id=109673
  [fdo#110818 ]: https://bugs.freedesktop.org/show_bug.cgi?id=110818 


Participating hosts (51 -> 45)
------------------------------

  Additional (1): fi-skl-6770hq 
  Missing    (7): fi-ilk-m540 fi-hsw-4200u fi-bsw-cyan fi-byt-clapper fi-kbl-7560u fi-icl-dsi fi-bdw-samus 


Build changes
-------------

  * Linux: CI_DRM_6180 -> Patchwork_13157

  CI_DRM_6180: e724dd1cacd9da18b18808880a13b0cb33ddd3d7 @ git://anongit.freedesktop.org/gfx-ci/linux
  IGT_5027: c998ca40a12933a0cefbe6b99c916eae32846919 @ git://anongit.freedesktop.org/xorg/app/intel-gpu-tools
  Patchwork_13157: 55290c7783043233509a583b5ef3bcea07ae89d1 @ git://anongit.freedesktop.org/gfx-ci/linux


== Linux commits ==

55290c778304 video/hdmi: Dropped static functions from kernel doc
6e17572de21e drm: Fix docbook warnings in hdr metadata helper structures
45a1461523e7 drm: ADD UAPI structure definition section in kernel doc

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_13157/
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx