[PATCH 9/9] drm/xe: Add __must_check for xe_force_wake_get

[Nirmoy Das]

Return value of xe_force_wake_get()  should not be ignored. So add
a __must_check attribute. Also add documentation for all related functions.

Signed-off-by: Nirmoy Das <nirmoy.das at intel.com>
---
 drivers/gpu/drm/xe/xe_force_wake.c | 27 +++++++++++++++++++++++++--
 drivers/gpu/drm/xe/xe_force_wake.h |  4 ++--
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/drivers/gpu/drm/xe/xe_force_wake.c b/drivers/gpu/drm/xe/xe_force_wake.c
index 9eef4ebaeccc..4d77f41fbf14 100644
--- a/drivers/gpu/drm/xe/xe_force_wake.c
+++ b/drivers/gpu/drm/xe/xe_force_wake.c
@@ -138,8 +138,20 @@ static int domain_sleep_wait(struct xe_gt *gt,
 					 (ffs(tmp__) - 1))) && \
 					 domain__->reg_ctl.addr)
 
-int xe_force_wake_get(struct xe_force_wake *fw,
-		      enum xe_force_wake_domains domains)
+/**
+ * xe_force_wake_get - Wake up the specified force wake domains if any are asleep
+ * @fw: Pointer to the force wake structure
+ * @domains: Bitmask representing the domains to be woken up
+ *
+ * This function ensures that the required domains are active and increments the
+ * reference count for each domain specified. If a domain was not previously active,
+ * it will be woken up. Logs an error message if any domain fails to acknowledge the
+ * wake-up request.
+ *
+ * Return: 0 on success, non-zero on failure.
+ */
+int __must_check xe_force_wake_get(struct xe_force_wake *fw,
+				   enum xe_force_wake_domains domains)
 {
 	struct xe_device *xe = fw_to_xe(fw);
 	struct xe_gt *gt = fw_to_gt(fw);
@@ -168,6 +180,17 @@ int xe_force_wake_get(struct xe_force_wake *fw,
 	return ret2;
 }
 
+/**
+ * xe_force_wake_put - Put the specified force wake domains to sleep when ref count becomes 0
+ * @fw: Pointer to the force wake structure
+ * @domains: Bitmask representing the domains to be put to sleep
+ *
+ * This function decrements the reference count for each domain specified. If a
+ * domain's reference count reaches zero, it will be put to sleep. Logs an error
+ * message if any domain fails to acknowledge the sleep request.
+ *
+ * Return: 0 on success, non-zero on failure.
+ */
 int xe_force_wake_put(struct xe_force_wake *fw,
 		      enum xe_force_wake_domains domains)
 {
diff --git a/drivers/gpu/drm/xe/xe_force_wake.h b/drivers/gpu/drm/xe/xe_force_wake.h
index 3f918a09f029..90948bf0054f 100644
--- a/drivers/gpu/drm/xe/xe_force_wake.h
+++ b/drivers/gpu/drm/xe/xe_force_wake.h
@@ -15,8 +15,8 @@ void xe_force_wake_init_gt(struct xe_gt *gt,
 			   struct xe_force_wake *fw);
 void xe_force_wake_init_engines(struct xe_gt *gt,
 				struct xe_force_wake *fw);
-int xe_force_wake_get(struct xe_force_wake *fw,
-		      enum xe_force_wake_domains domains);
+int __must_check xe_force_wake_get(struct xe_force_wake *fw,
+				   enum xe_force_wake_domains domains);
 int __must_check xe_force_wake_tryget(struct xe_force_wake *fw,
 				      enum xe_force_wake_domains domains);
 int xe_force_wake_put(struct xe_force_wake *fw,
-- 
2.42.0