[PATCH] drm/doc: Add kernel-doc for struct drm_mode_card_res

[Baba Dan Constantin]

Add missing kernel-doc documentation for struct drm_mode_card_res
used by the DRM_IOCTL_MODE_GETRESOURCES ioctl.

Signed-off-by: Baba Dan Constantin <babadany2999@xxxxxxxxx>
---
 include/uapi/drm/drm_mode.h | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index 381a3e857d4e..5db85b559bf6 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -249,18 +249,54 @@ struct drm_mode_modeinfo {
 	char name[DRM_DISPLAY_MODE_LEN];
 };
 
+/**
+ * struct drm_mode_card_res - Get GPU card resources metadata.
+ *
+ * User-space can perform a GETRESOURCES ioctl to retrieve information about a
+ * GPU card. User-space is expected to retrieve framebuffers, CRTC objects,
+ * connectors and encoders by performing this ioctl at least twice: the first
+ * time to retrieve the number of elements, the second time to retrieve the
+ * elements themselves.
+ *
+ * To retrieve the number of elements, set @count_fbs, @count_crtcs,
+ * @count_connectors and @count_encoders to 0.
+ *
+ * To retrieve the elements, allocate arrays for @fb_id_ptr, @crtc_id_ptr,
+ * @connector_id_ptr and @encoder_id_ptr to their capacity.
+ *
+ * Performing the ioctl only twice may be racy: the number of elements may have
+ * changed with a hotplug event in-between the two ioctls. User-space is expected
+ * to retry the last ioctl until the number of elements stabilizes.
+ *
+ * Unlike GETCONNECTOR, GETRESOURCES will fill arrays up to the provided count
+ * capacity, even if the actual element count has increased.
+ */
 struct drm_mode_card_res {
+	/** @fb_id_ptr: Pointer to ``__u32`` array of framebuffer IDs. */
 	__u64 fb_id_ptr;
+	/** @crtc_id_ptr: Pointer to ``__u32`` array of CRTC IDs.  */
 	__u64 crtc_id_ptr;
+	/** @connector_id_ptr: Pointer to ``__u32`` array of connector IDs. */
 	__u64 connector_id_ptr;
+	/** @encoder_id_ptr: Pointer to ``__u32`` array of encoder IDs. */
 	__u64 encoder_id_ptr;
+
+	/** @count_fbs: Number of framebuffers. */
 	__u32 count_fbs;
+	/** @count_crtcs: Number of CRTCs. */
 	__u32 count_crtcs;
+	/** @count_connectors: Number of connectors. */
 	__u32 count_connectors;
+	/** @count_encoders: Number of encoders. */
 	__u32 count_encoders;
+
+	/** @min_width: Minimum framebuffer width supported by this GPU card. */
 	__u32 min_width;
+	/** @max_width: Maximum framebuffer width supported by this GPU card. */
 	__u32 max_width;
+	/** @min_height: Minimum framebuffer height supported by this GPU card. */
 	__u32 min_height;
+	/** @max_height: Maximum framebuffer height supported by this GPU card. */
 	__u32 max_height;
 };
 
-- 
2.54.0