[PATCH v2 00/39] drm/i915: fix kernel-doc issues

[PATCH v2 00/39] drm/i915: fix kernel-doc issues

[Mauro Carvalho Chehab]

There are several kernel-doc markups along the i915 driver that aren't part
of the i915.rst file, nor are included on any other file under Documentation.
Maybe due to that, there are several kernel-doc markups that report problems
when checked with scripts/kernel-doc. More than that, some of them also
have problems when actually integrated at the building system, as reported
by Sphinx.

Along the issues we have:

- renamed symbols where the prototype doesn't match the kernel-doc name;
- some markups doesn't have the symbol name on it;
- typos when defining parameter;
- some parameters are missing;
- some ascii artwork aren't properly displayed after parsed by Sphinx;
- some other tags produce bad results and warnings after parsed by html build;
- some "/**" patterns exist on places that aren't kernel-doc markups.

This series, against drm-tip, fix all the above issues and all all such files to
i915.rst. This way, it will be easier to avoid other problems to be introduced.

While here, I also added SPDX on two display files. Besides being the current
way to indicate the license, it also makes easier to find all files with kernel-doc
markups, as all it is needed is to search for "/**" at i915 files to know what of
them have embedded documentation.

PS.: my end goal here is to ensure that the TLB patch series I'm about to
send will be properly documented. For that to happen, let's first fix all
warnings when building the documentation ;-)

---

v2:
- Added 3 already-existing patches form other PRs addressing some of the
  issues. The subjects were renamed, in order to describe what they're
  doing.
- Fixed checkpatch warnings;
- Added 4 additional patches at the end, documenting some structs
  at i915_gem_object_types.h and  intel_gt_pm.h, plus adding 
  intel-guc.c internal functions to the generated documentation.

Jiapeng Chong (3):
  drm/i915/gvt: Fix kernel-doc for intel_gvt_switch_mmio()
  drm/i915/gvt: Fix kernel-doc for intel_vgpu_default_mmio_write
  drm/i915/gvt: Fix kernel-doc for intel_vgpu_*_resource()

Mauro Carvalho Chehab (36):
  drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files
  drm/i915: display: fix kernel-doc markup warnings
  drm/i915: gt: fix some Kernel-doc issues
  drm/i915: gvt: fix kernel-doc trivial warnings
  drm/i915: gem: fix some Kernel-doc issues
  drm/i915: intel_wakeref.h: fix some kernel-doc markups
  drm/i915: i915_gem_ttm: fix a kernel-doc markup
  drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups
  drm/i915: gem: add kernel-doc description for some function parameters
  drm/i915: i915_gpu_error.c: document dump_flags
  drm/i915: document kernel-doc trivial issues
  drm/i915: intel_dp_link_training.c: fix kernel-doc markup
  drm/i915: intel_fb: fix a kernel-doc issue with Sphinx
  drm/i915: skl_scaler: fix return value kernel-doc markup
  drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc
  drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc
  drm/i915: i915_gem_wait.c: fix a kernel-doc markup
  drm/i915: fix i915_gem_ttm_move.c DOC: markup
  drm/i915: stop using kernel-doc markups for something else
  drm/i915: dvo_ch7xxx.c: use SPDX header
  drm/i915: dvo_sil164.c: use SPDX header
  drm/i915: i915_vma_resource.c: fix some kernel-doc markups
  drm/i915: i915_gem.c fix a kernel-doc issue
  drm/i915: i915_scatterlist.h: fix some kernel-doc markups
  drm/i915: i915_deps: use a shorter title markup
  docs: gpu: i915.rst: display: add kernel-doc markups
  docs: gpu: i915.rst: gt: add more kernel-doc markups
  docs: gpu: i915.rst: GuC: add more kernel-doc markups
  docs: gpu: i915.rst: GVT: add more kernel-doc markups
  docs: gpu: i915.rst: PM: add more kernel-doc markups
  docs: gpu: i915.rst: GEM/TTM: add more kernel-doc markups
  docs: gpu: i915.rst: add the remaining kernel-doc markup files
  drm/i915 i915_gem_object_types.h: document struct i915_lut_handle
  drm/i915: document struct drm_i915_gem_object
  drm/i915: add descriptions for some RPM macros at intel_gt_pm.h
  drm/i915: add GuC functions to the documentation

 Documentation/gpu/i915.rst                    | 288 ++++++++++++++++++
 drivers/gpu/drm/i915/display/dvo_ch7017.c     |  26 +-
 drivers/gpu/drm/i915/display/dvo_ch7xxx.c     |  39 +--
 drivers/gpu/drm/i915/display/dvo_sil164.c     |  32 +-
 .../drm/i915/display/intel_display_debugfs.c  |   2 +-
 .../drm/i915/display/intel_display_power.c    |   2 +-
 .../drm/i915/display/intel_display_types.h    |   2 +-
 .../drm/i915/display/intel_dp_link_training.c |   2 +
 drivers/gpu/drm/i915/display/intel_dvo_dev.h  |   6 +-
 drivers/gpu/drm/i915/display/intel_fb.c       |   2 +-
 drivers/gpu/drm/i915/display/intel_sdvo.c     |   4 +-
 drivers/gpu/drm/i915/display/intel_tc.c       |   2 +-
 drivers/gpu/drm/i915/display/intel_tv.c       |   2 +-
 drivers/gpu/drm/i915/display/skl_scaler.c     |   6 +-
 drivers/gpu/drm/i915/gem/i915_gem_create.c    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_domain.c    |  17 +-
 drivers/gpu/drm/i915/gem/i915_gem_object.c    |   2 +
 drivers/gpu/drm/i915/gem/i915_gem_object.h    |   2 +-
 .../gpu/drm/i915/gem/i915_gem_object_types.h  | 212 ++++++++++---
 drivers/gpu/drm/i915/gem/i915_gem_region.h    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_ttm.c       |   2 +
 drivers/gpu/drm/i915/gem/i915_gem_ttm.h       |   1 +
 drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c  |   4 +-
 drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_wait.c      |  26 +-
 drivers/gpu/drm/i915/gt/intel_context.h       |   6 +-
 drivers/gpu/drm/i915/gt/intel_context_types.h |  63 ++--
 drivers/gpu/drm/i915/gt/intel_engine_cs.c     |   4 +-
 drivers/gpu/drm/i915/gt/intel_engine_types.h  |   1 +
 drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h  |   2 +-
 drivers/gpu/drm/i915/gt/intel_gt_pm.h         |  62 ++++
 drivers/gpu/drm/i915/gt/intel_gt_types.h      |  12 +-
 drivers/gpu/drm/i915/gt/intel_gtt.h           |   6 +-
 drivers/gpu/drm/i915/gt/intel_reset_types.h   |   4 +-
 drivers/gpu/drm/i915/gt/intel_rps.c           |   4 +-
 .../gpu/drm/i915/gt/intel_timeline_types.h    |   6 +-
 .../drm/i915/gt/shaders/clear_kernel/hsw.asm  |   4 +-
 .../drm/i915/gt/shaders/clear_kernel/ivb.asm  |   4 +-
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h |  24 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |   2 +-
 .../gpu/drm/i915/gt/uc/intel_guc_hwconfig.c   |   5 +-
 drivers/gpu/drm/i915/gvt/aperture_gm.c        |   4 +-
 drivers/gpu/drm/i915/gvt/cfg_space.c          |   2 +-
 drivers/gpu/drm/i915/gvt/dmabuf.h             |   2 +-
 drivers/gpu/drm/i915/gvt/handlers.c           |   2 +-
 drivers/gpu/drm/i915/gvt/mmio_context.c       |   2 +-
 drivers/gpu/drm/i915/gvt/page_track.c         |   2 +-
 drivers/gpu/drm/i915/gvt/vgpu.c               |   6 +-
 drivers/gpu/drm/i915/i915_active.h            |  14 +-
 drivers/gpu/drm/i915/i915_deps.c              |   4 +-
 drivers/gpu/drm/i915/i915_drm_client.h        |   2 +-
 drivers/gpu/drm/i915/i915_drv.h               |  30 +-
 drivers/gpu/drm/i915/i915_file_private.h      |   8 +-
 drivers/gpu/drm/i915/i915_gem.c               |  12 +-
 drivers/gpu/drm/i915/i915_gpu_error.c         |   3 +-
 drivers/gpu/drm/i915/i915_gpu_error.h         |   4 +-
 drivers/gpu/drm/i915/i915_pmu.h               |  38 +--
 drivers/gpu/drm/i915/i915_request.h           |   4 +-
 drivers/gpu/drm/i915/i915_scatterlist.c       |   2 +-
 drivers/gpu/drm/i915/i915_scatterlist.h       |  12 +-
 drivers/gpu/drm/i915/i915_utils.h             |   2 +-
 drivers/gpu/drm/i915/i915_vma.c               |   2 +
 drivers/gpu/drm/i915/i915_vma_resource.c      |   4 +-
 drivers/gpu/drm/i915/i915_vma_resource.h      |   3 +-
 drivers/gpu/drm/i915/intel_pm.c               |  33 +-
 drivers/gpu/drm/i915/intel_region_ttm.c       |   3 +-
 drivers/gpu/drm/i915/intel_uncore.h           |   4 +-
 drivers/gpu/drm/i915/intel_wakeref.h          |   4 +-
 68 files changed, 795 insertions(+), 327 deletions(-)

-- 
2.36.1

[PATCH v2 29/39] docs: gpu: i915.rst: display: add kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented kAPI at the display side that
aren't currently part of the docs. Add them, as this allows
identifying issues with badly-formatted tags.

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 | 50 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 4e59db1cfb00..2ad7941a79f2 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -100,6 +100,56 @@ Display FIFO Underrun Reporting
 .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
    :internal:
 
+Atomic Modeset Support
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic.c
+
+Display Power Domain
+--------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power_map.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power_well.c
+
+Misc display functions
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_backlight.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_crtc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_connector.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_debugfs.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp_link_training.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fb.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fb_pin.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_gmbus.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lvds.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_opregion.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_snps_phy.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/intel_tc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
+
+
 Plane Configuration
 -------------------
 
-- 
2.36.1

[PATCH v2 30/39] docs: gpu: i915.rst: gt: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GT kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

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 | 43 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 2ad7941a79f2..afd8c0e3c689 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -149,7 +149,6 @@ Misc display functions
 
 .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
 
-
 Plane Configuration
 -------------------
 
@@ -308,6 +307,48 @@ Multicast/Replicated (MCR) Registers
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
    :internal:
 
+GT engine
+---------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
+
+GT context
+----------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h
+
+Graphics Translation Tables
+---------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
+
+Other GT functionality
+----------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
+
 Memory Management and Command Submission
 ========================================
 
-- 
2.36.1

[PATCH v2 31/39] docs: gpu: i915.rst: GuC: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GuC kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

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 | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index afd8c0e3c689..70f2f4826eba 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -596,6 +596,28 @@ GuC
 
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
 
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_slpc_abi.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ct.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ct.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_log.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw.c
+
 GuC Firmware Layout
 ~~~~~~~~~~~~~~~~~~~
 
-- 
2.36.1

[PATCH v2 32/39] docs: gpu: i915.rst: GVT: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GVT kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

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 | 41 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 70f2f4826eba..3ee121a0ea62 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -58,6 +58,47 @@ Intel GVT-g Host Support(vGPU device model)
 .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
    :internal:
 
+Other Intel GVT-g interfaces
+----------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/gvt.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/aperture_gm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/cfg_space.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/debugfs.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/display.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/edid.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/fb_decoder.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/firmware.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/gtt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/handlers.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/interrupt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/kvmgt.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt_mmio_table.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/mmio.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/mmio_context.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/opregion.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/page_track.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/scheduler.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gvt/vgpu.c
+
 Workarounds
 -----------
 
-- 
2.36.1

[PATCH v2 33/39] docs: gpu: i915.rst: PM: add more kernel-doc markups

[Mauro Carvalho Chehab]

Both intel_runtime_pm.h and intel_pm.c contains kAPI for
runtime PM. So, add them to the documentation.

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 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 3ee121a0ea62..c32409c03d32 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -25,6 +25,10 @@ Runtime Power Management
 .. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c
    :internal:
 
+.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
+
 Interrupt Handling
 ------------------
 
-- 
2.36.1

[PATCH v2 34/39] docs: gpu: i915.rst: GEM/TTM: add more kernel-doc markups

[Mauro Carvalho Chehab]

There are several documented GEM/TTM kAPI that aren't currently part
of the docs. Add them, as this allows identifying issues with
badly-formatted tags.

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 | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index c32409c03d32..974754586be8 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -615,6 +615,44 @@ Protected Objects
 
 .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h
 
+Table Manager (TTM)
+-------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
+
+Graphics Execution Manager (GEM)
+--------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_internal.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_lmem.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_mman.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object_types.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_region.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_region.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_userptr.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_wait.c
+
 Microcontrollers
 ================
 
-- 
2.36.1

[PATCH v2 35/39] docs: gpu: i915.rst: add the remaining kernel-doc markup files

[Mauro Carvalho Chehab]

There are other files with kernel-doc markups:

	$ git grep -l "/\*\*" $(git ls-files|grep drivers/gpu/drm/i915/) >kernel-doc-files
	$ for i in $(cat kernel-doc-files); do if [ "$(git grep $i Documentation/)" == "" ]; then echo "$i"; fi; done >aaa

Add them to i915.rst as well.

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 | 87 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 974754586be8..6bb50edc6d79 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -13,6 +13,11 @@ Core Driver Infrastructure
 This section covers core driver infrastructure used by both the display
 and the GEM parts of the driver.
 
+Core driver
+-----------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_driver.c
+
 Runtime Power Management
 ------------------------
 
@@ -29,6 +34,10 @@ Runtime Power Management
 
 .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
 
+.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h
+
 Interrupt Handling
 ------------------
 
@@ -44,6 +53,28 @@ Interrupt Handling
 .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
    :functions: intel_runtime_pm_enable_interrupts
 
+Error handling
+--------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c
+
+Memory Handling
+---------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_mm.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_memory_region.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_memcpy.c
+
 Intel GVT-g Guest Support(vGPU)
 -------------------------------
 
@@ -109,6 +140,54 @@ Workarounds
 .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
    :doc: Hardware workarounds
 
+32-bits compatible ioctl Logic
+------------------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
+
+Scatterlist handling
+--------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.c
+
+i915 request
+------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_request.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_request.c
+
+Ancillary routines
+------------------
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_device_info.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_params.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_sw_fence_work.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_syncmap.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_pcode.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_reg_defs.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.h
+
+
+PXP
+---
+
+.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_irq.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_tee.c
+
 Display Hardware Handling
 =========================
 
@@ -618,6 +697,12 @@ Protected Objects
 Table Manager (TTM)
 -------------------
 
+.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.h
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.c
+
+.. kernel-doc:: drivers/gpu/drm/i915/intel_region_ttm.c
+
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
 
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
@@ -627,6 +712,8 @@ Table Manager (TTM)
 Graphics Execution Manager (GEM)
 --------------------------------
 
+.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
+
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
 
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c
-- 
2.36.1

[PATCH v2 38/39] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h

[Mauro Carvalho Chehab]

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

[PATCH v2 39/39] drm/i915: add GuC functions to the documentation

[Mauro Carvalho Chehab]

Currently, functions inside GuC aren't presented as part of the
GuC documentation.

Add them.

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 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index 9862d504df4d..8c21a90d8b5a 100644
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -768,6 +768,9 @@ GuC
 
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
 
+.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
+   :internal:
+
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_slpc_abi.h
 
 .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
-- 
2.36.1

Re: [PATCH v2 32/39] docs: gpu: i915.rst: GVT: add more kernel-doc markups

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:20AM +0100, Mauro Carvalho Chehab wrote:
> There are several documented GVT kAPI that aren't currently part
> of the docs. Add them, as this allows identifying issues with
> badly-formatted tags.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

I haven't checked if these would be all the files, but the approach
looks reasonable to me.


Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

> ---
> 
> 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 | 41 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 41 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 70f2f4826eba..3ee121a0ea62 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -58,6 +58,47 @@ Intel GVT-g Host Support(vGPU device model)
>  .. kernel-doc:: drivers/gpu/drm/i915/intel_gvt.c
>     :internal:
>  
> +Other Intel GVT-g interfaces
> +----------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/gvt.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/aperture_gm.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/cfg_space.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/debugfs.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/display.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/edid.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/fb_decoder.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/firmware.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/gtt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/handlers.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/interrupt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/kvmgt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_gvt_mmio_table.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/mmio.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/mmio_context.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/opregion.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/page_track.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/scheduler.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gvt/vgpu.c
> +
>  Workarounds
>  -----------
>  
> -- 
> 2.36.1
> 

Re: [Intel-gfx] [PATCH v2 29/39] docs: gpu: i915.rst: display: add kernel-doc markups

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:17AM +0100, Mauro Carvalho Chehab wrote:
> There are several documented kAPI at the display side that
> aren't currently part of the docs. Add them, as this allows
> identifying issues with badly-formatted tags.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

same here, not checked if these would be all the files, but it is reasonable

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>



> ---
> 
> 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 | 50 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 50 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 4e59db1cfb00..2ad7941a79f2 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -100,6 +100,56 @@ Display FIFO Underrun Reporting
>  .. kernel-doc:: drivers/gpu/drm/i915/display/intel_fifo_underrun.c
>     :internal:
>  
> +Atomic Modeset Support
> +----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_atomic.c
> +
> +Display Power Domain
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power_map.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_power_well.c
> +
> +Misc display functions
> +----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_backlight.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_crtc.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_connector.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_display_debugfs.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dp_link_training.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpll.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_dpt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fb.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_fb_pin.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_gmbus.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_lvds.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_opregion.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_snps_phy.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/intel_tc.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
> +
> +
>  Plane Configuration
>  -------------------
>  
> -- 
> 2.36.1
> 

Re: [Intel-gfx] [PATCH v2 30/39] docs: gpu: i915.rst: gt: add more kernel-doc markups

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:18AM +0100, Mauro Carvalho Chehab wrote:
> There are several documented GT kAPI that aren't currently part
> of the docs. Add them, as this allows identifying issues with
> badly-formatted tags.
> 
> 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 | 43 +++++++++++++++++++++++++++++++++++++-
>  1 file changed, 42 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 2ad7941a79f2..afd8c0e3c689 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -149,7 +149,6 @@ Misc display functions
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
>  
> -
>  Plane Configuration
>  -------------------
>  
> @@ -308,6 +307,48 @@ Multicast/Replicated (MCR) Registers
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
>     :internal:
>  
> +GT engine
> +---------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
> +
> +GT context
> +----------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h

why does the context deserves a separated section and the
many others below no?

> +
> +Graphics Translation Tables
> +---------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
> +
> +Other GT functionality
> +----------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h

Why aren't these gtt ones in the above block? why only
having the global gtt there?

> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
> +
>  Memory Management and Command Submission
>  ========================================
>  
> -- 
> 2.36.1
> 

Re: [Intel-gfx] [PATCH v2 34/39] docs: gpu: i915.rst: GEM/TTM: add more kernel-doc markups

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:22AM +0100, Mauro Carvalho Chehab wrote:
> There are several documented GEM/TTM kAPI that aren't currently part
> of the docs. Add them, as this allows identifying issues with
> badly-formatted tags.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> ---
> 
> 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 | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index c32409c03d32..974754586be8 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -615,6 +615,44 @@ Protected Objects
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_types.h
>  
> +Table Manager (TTM)
> +-------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c
> +
> +Graphics Execution Manager (GEM)
> +--------------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_internal.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_lmem.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_mman.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_object_types.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_region.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_region.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_userptr.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_wait.c
> +
>  Microcontrollers
>  ================
>  
> -- 
> 2.36.1
> 

Re: [Intel-gfx] [PATCH v2 33/39] docs: gpu: i915.rst: PM: add more kernel-doc markups

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:21AM +0100, Mauro Carvalho Chehab wrote:
> Both intel_runtime_pm.h and intel_pm.c contains kAPI for
> runtime PM. So, add them to the documentation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> ---
> 
> 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 | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 3ee121a0ea62..c32409c03d32 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -25,6 +25,10 @@ Runtime Power Management
>  .. kernel-doc:: drivers/gpu/drm/i915/intel_uncore.c
>     :internal:
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_runtime_pm.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
> +
>  Interrupt Handling
>  ------------------
>  
> -- 
> 2.36.1
> 

Re: [Intel-gfx] [PATCH v2 38/39] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:26AM +0100, Mauro Carvalho Chehab wrote:
> 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

I don't believe this is the right placement for this.

the rest lgtm

> +
>  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
> 

Re: [PATCH v2 31/39] docs: gpu: i915.rst: GuC: add more kernel-doc markups

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:19AM +0100, Mauro Carvalho Chehab wrote:
> There are several documented GuC kAPI that aren't currently part
> of the docs. Add them, as this allows identifying issues with
> badly-formatted tags.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
> ---
> 
> 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 | 22 ++++++++++++++++++++++
>  1 file changed, 22 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index afd8c0e3c689..70f2f4826eba 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -596,6 +596,28 @@ GuC
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_slpc_abi.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ct.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ct.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_hwconfig.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_log.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_uc_fw.c
> +
>  GuC Firmware Layout
>  ~~~~~~~~~~~~~~~~~~~
>  
> -- 
> 2.36.1
> 

Re: [PATCH v2 39/39] drm/i915: add GuC functions to the documentation

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:27AM +0100, Mauro Carvalho Chehab wrote:
> Currently, functions inside GuC aren't presented as part of the
> GuC documentation.
> 
> Add them.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>

could be squashed to the other guc patch, but anyways:

Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

> ---
> 
> 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 | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 9862d504df4d..8c21a90d8b5a 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -768,6 +768,9 @@ GuC
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.h
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc.c
> +   :internal:
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/abi/guc_actions_slpc_abi.h
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c
> -- 
> 2.36.1
> 

Re: [Intel-gfx] [PATCH v2 35/39] docs: gpu: i915.rst: add the remaining kernel-doc markup files

[Rodrigo Vivi]

On Wed, Jul 13, 2022 at 09:12:23AM +0100, Mauro Carvalho Chehab wrote:
> There are other files with kernel-doc markups:
> 
> 	$ git grep -l "/\*\*" $(git ls-files|grep drivers/gpu/drm/i915/) >kernel-doc-files
> 	$ for i in $(cat kernel-doc-files); do if [ "$(git grep $i Documentation/)" == "" ]; then echo "$i"; fi; done >aaa
> 
> Add them to i915.rst as well.
> 
> 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 | 87 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 87 insertions(+)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 974754586be8..6bb50edc6d79 100644
> --- a/Documentation/gpu/i915.rst
> +++ b/Documentation/gpu/i915.rst
> @@ -13,6 +13,11 @@ Core Driver Infrastructure
>  This section covers core driver infrastructure used by both the display
>  and the GEM parts of the driver.
>  
> +Core driver
> +-----------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_driver.c
> +
>  Runtime Power Management
>  ------------------------
>  
> @@ -29,6 +34,10 @@ Runtime Power Management
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h

not sure if this belongs to this group...

> +
>  Interrupt Handling
>  ------------------
>  
> @@ -44,6 +53,28 @@ Interrupt Handling
>  .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
>     :functions: intel_runtime_pm_enable_interrupts
>  
> +Error handling
> +--------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c

not sure if this gt hang stuff deserves a separated section
alone and if the name is the best one....

> +
> +Memory Handling
> +---------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_mm.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_memory_region.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_memcpy.c
> +
>  Intel GVT-g Guest Support(vGPU)

                            ^ missing space

>  -------------------------------
>  
> @@ -109,6 +140,54 @@ Workarounds
>  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
>     :doc: Hardware workarounds
>  
> +32-bits compatible ioctl Logic
> +------------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
> +
> +Scatterlist handling
> +--------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.c
> +
> +i915 request
> +------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.c
> +
> +Ancillary routines

maybe simply have an "Others" section and put everything
that has only one item like the gpu hang one?

> +------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_device_info.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_params.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_sw_fence_work.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_syncmap.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_pcode.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_reg_defs.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.h
> +
> +
> +PXP

Protected Xe Path (PXP)


> +---
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_irq.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_tee.c
> +
>  Display Hardware Handling
>  =========================
>  
> @@ -618,6 +697,12 @@ Protected Objects
>  Table Manager (TTM)
>  -------------------
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.h
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.c
> +
> +.. kernel-doc:: drivers/gpu/drm/i915/intel_region_ttm.c
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> @@ -627,6 +712,8 @@ Table Manager (TTM)
>  Graphics Execution Manager (GEM)
>  --------------------------------
>  
> +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
> +
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
>  
>  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c

in many cases I see only the .h or only the .c... why is that?
wouldn't be better already put both in all the cases?

> -- 
> 2.36.1
> 

Re: [Intel-gfx] [PATCH v2 30/39] docs: gpu: i915.rst: gt: add more kernel-doc markups

[Mauro Carvalho Chehab]

On Tue, 9 Aug 2022 06:01:53 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> wrote:

> On Wed, Jul 13, 2022 at 09:12:18AM +0100, Mauro Carvalho Chehab wrote:
> > There are several documented GT kAPI that aren't currently part
> > of the docs. Add them, as this allows identifying issues with
> > badly-formatted tags.
> > 
> > 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 | 43 +++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 42 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 2ad7941a79f2..afd8c0e3c689 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -149,7 +149,6 @@ Misc display functions
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/display/skl_scaler.c
> >  
> > -
> >  Plane Configuration
> >  -------------------
> >  
> > @@ -308,6 +307,48 @@ Multicast/Replicated (MCR) Registers
> >  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gt_mcr.c
> >     :internal:
> >  
> > +GT engine
> > +---------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_types.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_cs.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_engine_pm.c
> > +
> > +GT context
> > +----------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_context.h  
> 
> why does the context deserves a separated section and the
> many others below no?

Good question. The patches adding stuff to i915.rst are the
hardest ones to produce, in the sense that it is not easy to have
a common criteria about when creating or not a new section.

I tried to follow the same as other things for the same type, but
it is hard to classify.

The main point is that they should be somewhere there, in order to start
producing errors when building the docs. Reorganizing those markups should
be easily done once all files with kernel-docs gets added there.

Anyway, I'll keep this under:

	Other GT functionality

Section. We can shift things later on as needed.

> > +
> > +Graphics Translation Tables
> > +---------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_ggtt.c
> > +
> > +Other GT functionality
> > +----------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gsc.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_gtt.h  
> 
> Why aren't these gtt ones in the above block? why only
> having the global gtt there?

Makes sense. I'll place GTT together with GGTT.

> 
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_migrate.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_mocs.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rc6.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_reset.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps_types.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_rps.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/gt/intel_sseu.c
> > +
> >  Memory Management and Command Submission
> >  ========================================
> >  
> > -- 
> > 2.36.1
> >   

Re: [Intel-gfx] [PATCH v2 35/39] docs: gpu: i915.rst: add the remaining kernel-doc markup files

[Mauro Carvalho Chehab]

On Tue, 9 Aug 2022 06:20:57 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> wrote:

> On Wed, Jul 13, 2022 at 09:12:23AM +0100, Mauro Carvalho Chehab wrote:
> > There are other files with kernel-doc markups:
> > 
> > 	$ git grep -l "/\*\*" $(git ls-files|grep drivers/gpu/drm/i915/) >kernel-doc-files
> > 	$ for i in $(cat kernel-doc-files); do if [ "$(git grep $i Documentation/)" == "" ]; then echo "$i"; fi; done >aaa
> > 
> > Add them to i915.rst as well.
> > 
> > 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 | 87 ++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 87 insertions(+)
> > 
> > diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> > index 974754586be8..6bb50edc6d79 100644
> > --- a/Documentation/gpu/i915.rst
> > +++ b/Documentation/gpu/i915.rst
> > @@ -13,6 +13,11 @@ Core Driver Infrastructure
> >  This section covers core driver infrastructure used by both the display
> >  and the GEM parts of the driver.
> >  
> > +Core driver
> > +-----------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_driver.c
> > +
> >  Runtime Power Management
> >  ------------------------
> >  
> > @@ -29,6 +34,10 @@ Runtime Power Management
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/intel_pm.c
> >  
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_wakeref.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_active.h  
> 
> not sure if this belongs to this group...
> 
> > +
> >  Interrupt Handling
> >  ------------------
> >  
> > @@ -44,6 +53,28 @@ Interrupt Handling
> >  .. kernel-doc:: drivers/gpu/drm/i915/i915_irq.c
> >     :functions: intel_runtime_pm_enable_interrupts
> >  
> > +Error handling
> > +--------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_gpu_error.c  
> 
> not sure if this gt hang stuff deserves a separated section
> alone and if the name is the best one....
> 
> > +
> > +Memory Handling
> > +---------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma_resource.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_vma.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_mm.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_memory_region.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_memcpy.c
> > +
> >  Intel GVT-g Guest Support(vGPU)  
> 
>                             ^ missing space
> 
> >  -------------------------------
> >  
> > @@ -109,6 +140,54 @@ Workarounds
> >  .. kernel-doc:: drivers/gpu/drm/i915/gt/intel_workarounds.c
> >     :doc: Hardware workarounds
> >  
> > +32-bits compatible ioctl Logic
> > +------------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ioc32.c
> > +
> > +Scatterlist handling
> > +--------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_scatterlist.c
> > +
> > +i915 request
> > +------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_request.c
> > +
> > +Ancillary routines  
> 
> maybe simply have an "Others" section and put everything
> that has only one item like the gpu hang one?

OK!

> 
> > +------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_deps.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_device_info.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_params.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_sw_fence_work.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_syncmap.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_pcode.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_reg_defs.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_wopcm.h
> > +
> > +
> > +PXP  
> 
> Protected Xe Path (PXP)
> 
> 
> > +---
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_irq.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/pxp/intel_pxp_tee.c
> > +
> >  Display Hardware Handling
> >  =========================
> >  
> > @@ -618,6 +697,12 @@ Protected Objects
> >  Table Manager (TTM)
> >  -------------------
> >  
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.h
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_ttm_buddy_manager.c
> > +
> > +.. kernel-doc:: drivers/gpu/drm/i915/intel_region_ttm.c
> > +
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.c
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_ttm.h
> > @@ -627,6 +712,8 @@ Table Manager (TTM)
> >  Graphics Execution Manager (GEM)
> >  --------------------------------
> >  
> > +.. kernel-doc:: drivers/gpu/drm/i915/i915_gem.c
> > +
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_create.c
> >  
> >  .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_domain.c  
> 
> in many cases I see only the .h or only the .c... why is that?
> wouldn't be better already put both in all the cases?

No. Adding kernel-doc files that doesn't contain any markups
will produce warnings.

We're working hard upstream to have a zero-warnings policy for
documentation.

Regards,
Mauro

Re: [Intel-gfx] [PATCH v2 38/39] drm/i915: add descriptions for some RPM macros at intel_gt_pm.h

[Mauro Carvalho Chehab]

On Tue, 9 Aug 2022 06:12:06 -0400
Rodrigo Vivi <rodrigo.vivi@intel.com> wrote:

> On Wed, Jul 13, 2022 at 09:12:26AM +0100, Mauro Carvalho Chehab wrote:
> > 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  
> 
> I don't believe this is the right placement for this.

I'll add it then at:

	Other GT functionality

Section.

Regards,
Mauro


> 
> the rest lgtm
> 
> > +
> >  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
> >