[PATCH 1/2] drm/doc: Document drm_get_encoder ioctl more thoroughly

[Ville Syrjala]

From: Ville Syrjälä <ville.syrjala at linux.intel.com>

Document all the fields of the drm_get_encoder ioctl.

Cc: Simon Ser <contact at emersion.fr>
Cc: Daniel Stone <daniels at collabora.com>
Signed-off-by: Ville Syrjälä <ville.syrjala at linux.intel.com>
---
 Documentation/gpu/drm-uapi.rst | 13 +++++++++++++
 include/uapi/drm/drm_mode.h    | 22 +++++++++++++++++++++-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
index 370d820be248..ebe318757b2a 100644
--- a/Documentation/gpu/drm-uapi.rst
+++ b/Documentation/gpu/drm-uapi.rst
@@ -564,6 +564,19 @@ CRTC ID's, and the CRTC index is its position in this array.
 .. kernel-doc:: include/uapi/drm/drm_mode.h
    :internal:
 
+encoder index
+-------------
+
+encoders have both an object ID and an index, and they are not the same thing.
+The index is used in cases where a densely packed identifier for an encoder is
+needed, for instance a bitmask of encoders. The member possible_clones of struct
+drm_mode_get_encoder is an example.
+
+:c:macro:`DRM_IOCTL_MODE_GETRESOURCES` populates a structure with an array of
+encoder IDs, and the encoder index is its position in this array.
+
+.. kernel-doc:: include/uapi/drm/drm_mode.h
+   :internal:
 
 dma-buf interoperability
 ========================
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index d390011b89b4..fe5e210396b2 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -373,12 +373,32 @@ struct drm_mode_get_plane_res {
 #define DRM_MODE_ENCODER_DPI	8
 
 struct drm_mode_get_encoder {
+	/**
+	 * @encoder_id: Object ID of the encoder whose information
+	 * should be retrieved. Set by caller.
+	 */
 	__u32 encoder_id;
+	/** @encoder_type: Type of the encoder */
 	__u32 encoder_type;
 
-	__u32 crtc_id; /**< Id of crtc */
+	/** @crtc_id: Object ID of the current CRTC. */
+	__u32 crtc_id;
 
+	/**
+	 * @possible_crtcs: Bitmask of CRTCs compatible with the encoder.
+	 * CRTCs are created and they receive an index, which corresponds
+	 * to their position in the bitmask. Bit N corresponds to
+	 * :ref:`CRTC index<crtc_index>` N.
+	 */
 	__u32 possible_crtcs;
+	/**
+	 * @possible_clones: Bitmask of encoders compatible with the
+	 * encoder for cloning. A set of cloned encoders all source
+	 * their data from the same CRTC.
+	 * Encoders are created and they receive an index, which corresponds
+	 * to their position in the bitmask. Bit N corresponds to
+	 * :ref:`encoder index<encoder_index>` N.
+	 */
 	__u32 possible_clones;
 };
 
-- 
2.44.2