mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab@kernel.org>
To: unlisted-recipients:; (no To-header on input)
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>,
	Daniel Vetter <daniel@ffwll.ch>, David Airlie <airlied@linux.ie>,
	Jani Nikula <jani.nikula@linux.intel.com>,
	John Harrison <John.C.Harrison@Intel.com>,
	Jonathan Corbet <corbet@lwn.net>,
	Joonas Lahtinen <joonas.lahtinen@linux.intel.com>,
	Maarten Lankhorst <maarten.lankhorst@linux.intel.com>,
	Matthew Brost <matthew.brost@intel.com>,
	Maxime Ripard <mripard@kernel.org>,
	Rodrigo Vivi <rodrigo.vivi@intel.com>,
	Thomas Zimmermann <tzimmermann@suse.de>,
	Tvrtko Ursulin <tvrtko.ursulin@linux.intel.com>,
	dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH v2 38/39] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h
Date: Wed, 13 Jul 2022 09:12:26 +0100	[thread overview]
Message-ID: <37e3b9aac85f1d08c0a53bae86680d504308bf67.1657699522.git.mchehab@kernel.org> (raw)
In-Reply-To: <cover.1657699522.git.mchehab@kernel.org>

The intel_gt_pm.h file contains some convenient macros to be used
in GT code in order to get/put runtime PM references and for
checking them.

Add descriptions based on the ones at intel_wakeref.h and
intel_runtime_pm.c.

Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
---

To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover.
See [PATCH v2 00/39] at: https://lore.kernel.org/all/cover.1657699522.git.mchehab@kernel.org/

 Documentation/gpu/i915.rst            |  2 +
 drivers/gpu/drm/i915/gt/intel_gt_pm.h | 62 +++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 6bb50edc6d79..9862d504df4d 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -709,6 +709,8 @@ Table Manager (TTM)
 
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
 
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_pm.h
+
 Graphics Execution Manager (GEM)
 --------------------------------
 
diff --git a/drivers/gpu/drm/i915/gt/intel_gt_pm.h b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
index bc898df7a48c..a8ea6846980a 100644
--- a/drivers/gpu/drm/i915/gt/intel_gt_pm.h
+++ b/drivers/gpu/drm/i915/gt/intel_gt_pm.h
@@ -11,21 +11,57 @@
 #include "intel_gt_types.h"
 #include "intel_wakeref.h"
 
+/**
+ * intel_gt_pm_is_awake: Query whether the runtime PM is awake held
+ *
+ * @gt: pointer to the graphics engine
+ *
+ * Returns: true if a runtime pm reference is currently held and the GT is
+ * awake.
+ */
 static inline bool intel_gt_pm_is_awake(const struct intel_gt *gt)
 {
 	return intel_wakeref_is_active(&gt->wakeref);
 }
 
+/**
+ * intel_gt_pm_get: grab a runtime PM reference ensuring that GT is powered up
+ * @gt: pointer to the graphics engine
+ *
+ * Any runtime pm reference obtained by this function must have a symmetric
+ * call to intel_gt_pm_put() to release the reference again.
+ *
+ * Note that this is allowed to fail, in which case the runtime-pm wakeref
+ * will be released and the acquisition unwound.
+ */
 static inline void intel_gt_pm_get(struct intel_gt *gt)
 {
 	intel_wakeref_get(&gt->wakeref);
 }
 
+/**
+ * __intel_gt_pm_get: Acquire the runtime PM reference again
+ * @gt: pointer to the graphics engine which contains the wakeref
+ *
+ * Increment the PM reference counter, only valid if it is already held by
+ * the caller.
+ *
+ * See intel_gt_pm_get().
+ */
 static inline void __intel_gt_pm_get(struct intel_gt *gt)
 {
 	__intel_wakeref_get(&gt->wakeref);
 }
 
+/**
+ * intel_gt_pm_get_if_awake: Acquire the runtime PM reference if active
+ * @gt: pointer to the graphics engine which contains the PM reference
+ *
+ * Acquire a hold on the PM reference, but only if the GT is already
+ * active.
+ *
+ * Returns: true if the wakeref was acquired, false otherwise.
+ */
 static inline bool intel_gt_pm_get_if_awake(struct intel_gt *gt)
 {
 	return intel_wakeref_get_if_active(&gt->wakeref);
@@ -36,6 +72,14 @@ static inline void intel_gt_pm_might_get(struct intel_gt *gt)
 	intel_wakeref_might_get(&gt->wakeref);
 }
 
+/**
+ * intel_gt_pm_put: Release the runtime PM reference
+ * @gt: pointer to the graphics engine which contains the PM reference
+ *
+ * Release our hold on the runtime PM for GT.
+ *
+ * It might power down the GT right away if this is the last reference.
+ */
 static inline void intel_gt_pm_put(struct intel_gt *gt)
 {
 	intel_wakeref_put(&gt->wakeref);
@@ -51,10 +95,28 @@ static inline void intel_gt_pm_might_put(struct intel_gt *gt)
 	intel_wakeref_might_put(&gt->wakeref);
 }
 
+/**
+ * with_intel_gt_pm - get a GT reference ensuring that GT is powered up,
+ *	run some code and then put the reference away.
+ *
+ * @gt: pointer to the gt
+ * @tmp: pointer to a temporary wakeref.
+ */
 #define with_intel_gt_pm(gt, tmp) \
 	for (tmp = 1, intel_gt_pm_get(gt); tmp; \
 	     intel_gt_pm_put(gt), tmp = 0)
 
+/**
+ * intel_gt_pm_wait_for_idle: Wait until the runtime PM reference is idle
+ * @gt: pointer to the graphics engine which contains the PM reference
+ *
+ * Wait for the earlier asynchronous release of the runtime PM reference. Note
+ * this will wait for any third party as well, so make sure you only wait
+ * when you have control over the GT runtime PM and trust no one else is
+ * acquiring it.
+ *
+ * Return: 0 on success, error code if killed.
+ */
 static inline int intel_gt_pm_wait_for_idle(struct intel_gt *gt)
 {
 	return intel_wakeref_wait_for_idle(&gt->wakeref);
-- 
2.36.1


  parent reply	other threads:[~2022-07-13  8:14 UTC|newest]

Thread overview: 89+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-07-13  8:11 [PATCH v2 00/39] drm/i915: fix kernel-doc issues Mauro Carvalho Chehab
2022-07-13  8:11 ` [PATCH v2 01/39] drm/i915/gvt: Fix kernel-doc for intel_gvt_switch_mmio() Mauro Carvalho Chehab
2022-07-13 21:54   ` Rodrigo Vivi
2022-07-13 22:00     ` Rodrigo Vivi
2022-07-14  8:50       ` [Intel-gfx] " Mauro Carvalho Chehab
2022-07-13  8:11 ` [PATCH v2 02/39] drm/i915/gvt: Fix kernel-doc for intel_vgpu_default_mmio_write Mauro Carvalho Chehab
2022-07-13 21:55   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:11 ` [PATCH v2 03/39] drm/i915/gvt: Fix kernel-doc for intel_vgpu_*_resource() Mauro Carvalho Chehab
2022-07-13 22:02   ` Rodrigo Vivi
2022-07-13  8:11 ` [PATCH v2 04/39] drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files Mauro Carvalho Chehab
2022-07-13 22:02   ` Rodrigo Vivi
2022-07-13  8:11 ` [PATCH v2 05/39] drm/i915: display: fix kernel-doc markup warnings Mauro Carvalho Chehab
2022-07-13 22:05   ` Rodrigo Vivi
2022-07-14  9:56     ` [Intel-gfx] " Mauro Carvalho Chehab
2022-07-13  8:11 ` [PATCH v2 06/39] drm/i915: gt: fix some Kernel-doc issues Mauro Carvalho Chehab
2022-07-13 22:07   ` [Intel-gfx] " Rodrigo Vivi
2022-07-14 10:01     ` Mauro Carvalho Chehab
2022-07-13  8:11 ` [PATCH v2 07/39] drm/i915: gvt: fix kernel-doc trivial warnings Mauro Carvalho Chehab
2022-07-13 22:08   ` Rodrigo Vivi
2022-07-14  4:23   ` Zhenyu Wang
2022-07-13  8:11 ` [PATCH v2 08/39] drm/i915: gem: fix some Kernel-doc issues Mauro Carvalho Chehab
2022-07-13  8:11 ` [PATCH v2 09/39] drm/i915: intel_wakeref.h: fix some kernel-doc markups Mauro Carvalho Chehab
2022-07-13 22:09   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:11 ` [PATCH v2 10/39] drm/i915: i915_gem_ttm: fix a kernel-doc markup Mauro Carvalho Chehab
2022-07-13  8:11 ` [PATCH v2 11/39] drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups Mauro Carvalho Chehab
2022-08-09 10:23   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 12/39] drm/i915: gem: add kernel-doc description for some function parameters Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 13/39] drm/i915: i915_gpu_error.c: document dump_flags Mauro Carvalho Chehab
2022-07-15 21:38   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 14/39] drm/i915: document kernel-doc trivial issues Mauro Carvalho Chehab
2022-07-15 21:31   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 15/39] drm/i915: intel_dp_link_training.c: fix kernel-doc markup Mauro Carvalho Chehab
2022-08-09  9:51   ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 18:53     ` Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 16/39] drm/i915: intel_fb: fix a kernel-doc issue with Sphinx Mauro Carvalho Chehab
2022-07-15 21:40   ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 18:58     ` Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 17/39] drm/i915: skl_scaler: fix return value kernel-doc markup Mauro Carvalho Chehab
2022-07-15 21:42   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 18/39] drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc Mauro Carvalho Chehab
2022-08-09  9:55   ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 19:17     ` Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 19/39] drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc Mauro Carvalho Chehab
2022-08-09  9:59   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 20/39] drm/i915: i915_gem_wait.c: fix a kernel-doc markup Mauro Carvalho Chehab
2022-07-15 21:25   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 21/39] drm/i915: fix i915_gem_ttm_move.c DOC: markup Mauro Carvalho Chehab
2022-07-15 21:41   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 22/39] drm/i915: stop using kernel-doc markups for something else Mauro Carvalho Chehab
2022-07-15 21:34   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 23/39] drm/i915: dvo_ch7xxx.c: use SPDX header Mauro Carvalho Chehab
2022-07-15 21:41   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 24/39] drm/i915: dvo_sil164.c: " Mauro Carvalho Chehab
2022-07-15 21:35   ` Rodrigo Vivi
2022-07-15 22:16     ` Joe Perches
2022-07-18 11:38       ` [Intel-gfx] " Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 25/39] drm/i915: i915_vma_resource.c: fix some kernel-doc markups Mauro Carvalho Chehab
2022-07-15 21:32   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 26/39] drm/i915: i915_gem.c fix a kernel-doc issue Mauro Carvalho Chehab
2022-07-15 21:26   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 27/39] drm/i915: i915_scatterlist.h: fix some kernel-doc markups Mauro Carvalho Chehab
2022-07-15 21:33   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 28/39] drm/i915: i915_deps: use a shorter title markup Mauro Carvalho Chehab
2022-07-15 21:32   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 29/39] docs: gpu: i915.rst: display: add kernel-doc markups Mauro Carvalho Chehab
2022-08-09  9:57   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 30/39] docs: gpu: i915.rst: gt: add more " Mauro Carvalho Chehab
2022-08-09 10:01   ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 19:35     ` Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 31/39] docs: gpu: i915.rst: GuC: " Mauro Carvalho Chehab
2022-08-09 10:12   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 32/39] docs: gpu: i915.rst: GVT: " Mauro Carvalho Chehab
2022-08-09  9:56   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 33/39] docs: gpu: i915.rst: PM: " Mauro Carvalho Chehab
2022-08-09 10:03   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 34/39] docs: gpu: i915.rst: GEM/TTM: " Mauro Carvalho Chehab
2022-08-09 10:02   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 35/39] docs: gpu: i915.rst: add the remaining kernel-doc markup files Mauro Carvalho Chehab
2022-08-09 10:20   ` [Intel-gfx] " Rodrigo Vivi
2022-09-06 19:43     ` Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 36/39] drm/i915 i915_gem_object_types.h: document struct i915_lut_handle Mauro Carvalho Chehab
2022-08-09 10:09   ` Rodrigo Vivi
2022-07-13  8:12 ` [PATCH v2 37/39] drm/i915: document struct drm_i915_gem_object Mauro Carvalho Chehab
2022-08-09 10:08   ` [Intel-gfx] " Rodrigo Vivi
2022-07-13  8:12 ` Mauro Carvalho Chehab [this message]
2022-08-09 10:12   ` [Intel-gfx] [PATCH v2 38/39] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h Rodrigo Vivi
2022-09-06 19:47     ` Mauro Carvalho Chehab
2022-07-13  8:12 ` [PATCH v2 39/39] drm/i915: add GuC functions to the documentation Mauro Carvalho Chehab
2022-08-09 10:13   ` Rodrigo Vivi

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=37e3b9aac85f1d08c0a53bae86680d504308bf67.1657699522.git.mchehab@kernel.org \
    --to=mchehab@kernel.org \
    --cc=John.C.Harrison@Intel.com \
    --cc=airlied@linux.ie \
    --cc=corbet@lwn.net \
    --cc=daniel@ffwll.ch \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=intel-gfx@lists.freedesktop.org \
    --cc=jani.nikula@linux.intel.com \
    --cc=joonas.lahtinen@linux.intel.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=maarten.lankhorst@linux.intel.com \
    --cc=matthew.brost@intel.com \
    --cc=mripard@kernel.org \
    --cc=rodrigo.vivi@intel.com \
    --cc=tvrtko.ursulin@linux.intel.com \
    --cc=tzimmermann@suse.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®