Re: [PATCH v2 01/30] drm/xe/forcewake: Improve kerneldoc

[Gustavo Sousa <gustavo.sousa@intel.com>]

Quoting Matt Roper (2025-11-10 20:20:19-03:00)
>Improve the kerneldoc for forcewake a bit to give more detail about what
>the structures represent.
>
>Signed-off-by: Matt Roper <matthew.d.roper@intel.com>
>---
> drivers/gpu/drm/xe/xe_force_wake_types.h | 26 ++++++++++++++++++++++--
> 1 file changed, 24 insertions(+), 2 deletions(-)
>
>diff --git a/drivers/gpu/drm/xe/xe_force_wake_types.h b/drivers/gpu/drm/xe/xe_force_wake_types.h
>index 12d6e2367455..9cfa28faf7bc 100644
>--- a/drivers/gpu/drm/xe/xe_force_wake_types.h
>+++ b/drivers/gpu/drm/xe/xe_force_wake_types.h
>@@ -52,7 +52,22 @@ enum xe_force_wake_domains {
> };
> 
> /**
>- * struct xe_force_wake_domain - Xe force wake domains
>+ * struct xe_force_wake_domain - Xe force wake power domain
>+ *
>+ * Represents a individual device-internal power domain.  The driver must

s/a individual/an individual/

Reviewed-by: Gustavo Sousa <gustavo.sousa@intel.com>

>+ * ensure the power domain is awake before accessing registers or other
>+ * hardware functionality that is part of the power domain.  Since different
>+ * driver threads may access hardware units simultaneously, a reference count
>+ * is used to ensure that the domain remains awake as long as any software
>+ * is using the part of the hardware covered by the power domain.
>+ *
>+ * Hardware provides a register interface to allow the driver to request
>+ * wake/sleep of power domains, although in most cases the actual action of
>+ * powering the hardware up/down is handled by firmware (and may be subject to
>+ * requirements and constraints outside of the driver's visibility) so the
>+ * driver needs to wait for an acknowledgment that a wake request has been
>+ * acted upon before accessing the parts of the hardware that reside within the
>+ * power domain.
>  */
> struct xe_force_wake_domain {
>         /** @id: domain force wake id */
>@@ -70,7 +85,14 @@ struct xe_force_wake_domain {
> };
> 
> /**
>- * struct xe_force_wake - Xe force wake
>+ * struct xe_force_wake - Xe force wake collection
>+ *
>+ * Represents a collection of related power domains (struct
>+ * xe_force_wake_domain) associated with a subunit of the device.
>+ *
>+ * Currently only used for GT power domains (where the term "forcewake" is used
>+ * in the hardware documentation), although the interface could be extended to
>+ * power wells in other parts of the hardware in the future.
>  */
> struct xe_force_wake {
>         /** @gt: back pointers to GT */
>-- 
>2.51.1
>