drm/imagination: Numerous documentation fixes.

Some reported by Stephen Rothwell. The rest were found by running the
kernel-doc build script.
Some indentation fixes.

Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Reported-by: kernel test robot <lkp@intel.com>
Closes: https://lore.kernel.org/oe-kbuild-all/202311241526.Y2WZeUau-lkp@intel.com/
Signed-off-by: Donald Robson <donald.robson@imgtec.com>
Signed-off-by: Maxime Ripard <mripard@kernel.org>
Link: https://patchwork.freedesktop.org/patch/msgid/20231128173507.95119-1-donald.robson@imgtec.com

diff --git a/Documentation/gpu/imagination/index.rst b/Documentation/gpu/imagination/index.rst
index dc9579e758c3ec9a3dbc504ce07e7991f01abe2e..0c1e247cea41eb3aad466b22806fa0b2c15ed65d 100644 (file)
--- a/Documentation/gpu/imagination/index.rst
+++ b/Documentation/gpu/imagination/index.rst
@@ -3,7 +3,7 @@ drm/imagination PowerVR Graphics Driver
 =======================================
 
 .. kernel-doc:: drivers/gpu/drm/imagination/pvr_drv.c
-   :doc: PowerVR Graphics Driver
+   :doc: PowerVR (Series 6 and later) and IMG Graphics Driver
 
 Contents
 ========

diff --git a/Documentation/gpu/imagination/uapi.rst b/Documentation/gpu/imagination/uapi.rst
index 2227ea7e6222c0aa6f8b84bb379d4026d3263937..7502413d0a939bb13a0df0cc0efebfcf69e5daf9 100644 (file)
--- a/Documentation/gpu/imagination/uapi.rst
+++ b/Documentation/gpu/imagination/uapi.rst
@@ -45,9 +45,6 @@ DEV_QUERY
                  drm_pvr_heap
                  drm_pvr_dev_query_heap_info
 
-.. kernel-doc:: include/uapi/drm/pvr_drm.h
-   :doc: Flags for DRM_PVR_DEV_QUERY_HEAP_INFO_GET.
-
 .. kernel-doc:: include/uapi/drm/pvr_drm.h
    :identifiers: drm_pvr_static_data_area_usage
                  drm_pvr_static_data_area
@@ -121,7 +118,7 @@ CREATE_FREE_LIST and DESTROY_FREE_LIST
    :identifiers: drm_pvr_ioctl_destroy_free_list_args
 
 CREATE_HWRT_DATASET and DESTROY_HWRT_DATASET
---------------------------------------
+--------------------------------------------
 .. kernel-doc:: include/uapi/drm/pvr_drm.h
    :doc: PowerVR IOCTL CREATE_HWRT_DATASET and DESTROY_HWRT_DATASET interfaces
 

diff --git a/drivers/gpu/drm/imagination/pvr_cccb.h b/drivers/gpu/drm/imagination/pvr_cccb.h
index f35b3d4c9575bc462345e06dbe8542b347e4d80e..943fe8f2c963be6c7e63d68442ff0f53ac0a9098 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_cccb.h
+++ b/drivers/gpu/drm/imagination/pvr_cccb.h
@@ -86,6 +86,7 @@ pvr_cccb_get_size_of_cmd_with_hdr(u32 cmd_size)
 
 /**
  * pvr_cccb_cmdseq_can_fit() - Check if a command sequence can fit in the CCCB.
+ * @pvr_cccb: Target Client CCB.
  * @size: Command sequence size.
  *
  * Returns:

diff --git a/drivers/gpu/drm/imagination/pvr_device.h b/drivers/gpu/drm/imagination/pvr_device.h
index e07655fc65e8c001d1d420be3e7bf1b062bdbe9e..2ca7e535799fefcd29261f6f20e4aff8a86fc10f 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_device.h
+++ b/drivers/gpu/drm/imagination/pvr_device.h
@@ -203,17 +203,29 @@ struct pvr_device {
                struct mutex lock;
        } queues;
 
+       /**
+        * @watchdog: Watchdog for communications with firmware.
+        */
        struct {
                /** @work: Work item for watchdog callback. */
                struct delayed_work work;
 
-               /** @old_kccb_cmds_executed: KCCB command execution count at last watchdog poll. */
+               /**
+                * @old_kccb_cmds_executed: KCCB command execution count at last
+                * watchdog poll.
+                */
                u32 old_kccb_cmds_executed;
 
-               /** @kccb_stall_count: Number of watchdog polls KCCB has been stalled for. */
+               /**
+                * @kccb_stall_count: Number of watchdog polls KCCB has been
+                * stalled for.
+                */
                u32 kccb_stall_count;
        } watchdog;
 
+       /**
+        * @kccb: Circular buffer for communications with firmware.
+        */
        struct {
                /** @ccb: Kernel CCB. */
                struct pvr_ccb ccb;
@@ -225,8 +237,8 @@ struct pvr_device {
                struct pvr_fw_object *rtn_obj;
 
                /**
-                * @rtn: Pointer to CPU mapping of KCCB return slots. Must be accessed by
-                *       READ_ONCE()/WRITE_ONCE().
+                * @rtn: Pointer to CPU mapping of KCCB return slots. Must be
+                * accessed by READ_ONCE()/WRITE_ONCE().
                 */
                u32 *rtn;
 
@@ -293,14 +305,13 @@ struct pvr_file {
 
        /**
         * @pvr_dev: A reference to the powervr-specific wrapper for the
-        *           associated device. Saves on repeated calls to
-        *           to_pvr_device().
+        * associated device. Saves on repeated calls to to_pvr_device().
         */
        struct pvr_device *pvr_dev;
 
        /**
         * @ctx_handles: Array of contexts belonging to this file. Array members
-        *               are of type "struct pvr_context *".
+        * are of type "struct pvr_context *".
         *
         * This array is used to allocate handles returned to userspace.
         */

diff --git a/drivers/gpu/drm/imagination/pvr_fw.h b/drivers/gpu/drm/imagination/pvr_fw.h
index 5cd3ef08d82b43682c00035c06b0016d38f90a47..b7966bd574a924862b7877c175fa2b5d757d89db 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_fw.h
+++ b/drivers/gpu/drm/imagination/pvr_fw.h
@@ -481,7 +481,8 @@ pvr_fw_object_unmap_and_destroy(struct pvr_fw_object *fw_obj)
 }
 
 /**
- * pvr_fw_get_dma_addr() - Get DMA address for given offset in firmware object
+ * pvr_fw_object_get_dma_addr() - Get DMA address for given offset in firmware
+ * object.
  * @fw_obj: Pointer to object to lookup address in.
  * @offset: Offset within object to lookup address at.
  * @dma_addr_out: Pointer to location to store DMA address.

diff --git a/drivers/gpu/drm/imagination/pvr_fw_info.h b/drivers/gpu/drm/imagination/pvr_fw_info.h
index ad5d44a3067ac2ec81a90e1f0c87ac3585a0af00..c3639440610eb16ce7118d32d0f90410db76d1be 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_fw_info.h
+++ b/drivers/gpu/drm/imagination/pvr_fw_info.h
@@ -122,13 +122,13 @@ struct pvr_fw_layout_entry {
  * struct pvr_fw_device_info_header - Device information header.
  */
 struct pvr_fw_device_info_header {
-       /* BRN Mask size (in u64s). */
+       /** @brn_mask_size: BRN mask size (in u64s). */
        u64 brn_mask_size;
-       /* ERN Mask size (in u64s). */
+       /** @ern_mask_size: ERN mask size (in u64s). */
        u64 ern_mask_size;
-       /* Feature Mask size (in u64s). */
+       /** @feature_mask_size: Feature mask size (in u64s). */
        u64 feature_mask_size;
-       /* Feature Parameter size (in u64s). */
+       /** @feature_param_size: Feature parameter size (in u64s). */
        u64 feature_param_size;
 };
 

diff --git a/drivers/gpu/drm/imagination/pvr_hwrt.h b/drivers/gpu/drm/imagination/pvr_hwrt.h
index 76992948d0472ed5422d7cca67cdbd98052b96d3..676070b20c3ba552319057cfcabe69c890dbc832 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_hwrt.h
+++ b/drivers/gpu/drm/imagination/pvr_hwrt.h
@@ -64,6 +64,7 @@ struct pvr_hwrt_dataset {
        /** @common_fw_obj: FW object representing common FW-side structure. */
        struct pvr_fw_object *common_fw_obj;
 
+       /** @common: Common HWRT data. */
        struct rogue_fwif_hwrtdata_common common;
 
        /** @data: HWRT data structures belonging to this set. */

diff --git a/drivers/gpu/drm/imagination/pvr_job.c b/drivers/gpu/drm/imagination/pvr_job.c
index 9d0812710295cfbc5ab578f159ed6a1aa400499e..04139da6c04dcd546930f8e29b1b8612941fef59 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_job.c
+++ b/drivers/gpu/drm/imagination/pvr_job.c
@@ -378,7 +378,7 @@ prepare_job_syncs(struct pvr_file *pvr_file,
 
 /**
  * prepare_job_syncs_for_each() - Prepare all sync objects for an array of jobs.
- * @file: PowerVR file.
+ * @pvr_file: PowerVR file.
  * @job_data: Array of precreated jobs and their sync_ops.
  * @job_count: Number of jobs.
  * @signal_array: xarray to receive signal sync objects.
@@ -696,8 +696,6 @@ pvr_jobs_link_geom_frag(struct pvr_job_data *job_data, u32 *job_count)
  * @pvr_dev: Target PowerVR device.
  * @pvr_file: Pointer to PowerVR file structure.
  * @args: Ioctl args.
- * @job_count: Number of jobs in @jobs_args. On error this will be updated
- * with the index into @jobs_args where the error occurred.
  *
  * This initial implementation is entirely synchronous; on return the GPU will
  * be idle. This will not be the case for future implementations.

diff --git a/drivers/gpu/drm/imagination/pvr_mmu.c b/drivers/gpu/drm/imagination/pvr_mmu.c
index b71d30e5f380521dfff6c95d5e971f3b597cbc94..c8562bfc0dcda35875c0c39ebb43816f60f01af0 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_mmu.c
+++ b/drivers/gpu/drm/imagination/pvr_mmu.c
@@ -335,8 +335,9 @@ pvr_mmu_backing_page_fini(struct pvr_mmu_backing_page *page)
 
 /**
  * pvr_mmu_backing_page_sync() - Flush a MMU backing page from the CPU to the
- *                              device.
+ * device.
  * @page: Target backing page.
+ * @flags: MMU flush flags. Must be one of %PVR_MMU_SYNC_LEVEL_*_FLAGS.
  *
  * .. caution::
  *

diff --git a/drivers/gpu/drm/imagination/pvr_queue.h b/drivers/gpu/drm/imagination/pvr_queue.h
index b5ce2c742150b2bd3d068a0d63f045fae60c86cf..e06ced69302fca47fc26451dfb09ebbb24b57f52 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_queue.h
+++ b/drivers/gpu/drm/imagination/pvr_queue.h
@@ -50,7 +50,7 @@ struct pvr_queue_cccb_fence_ctx {
         */
        struct pvr_job *job;
 
-       /** @lock: Lock protecting access to the job object. */
+       /** @job_lock: Lock protecting access to the job object. */
        struct mutex job_lock;
 };
 
@@ -114,7 +114,7 @@ struct pvr_queue {
        } timeline_ufo;
 
        /**
-        * last_queued_job_scheduled_fence: The scheduled fence of the last
+        * @last_queued_job_scheduled_fence: The scheduled fence of the last
         * job queued to this queue.
         *
         * We use it to insert frag -> geom dependencies when issuing combined

diff --git a/drivers/gpu/drm/imagination/pvr_vm.c b/drivers/gpu/drm/imagination/pvr_vm.c
index e0d74d9a61909fc49bfb6d961a9aa32ab59a032d..2aab53594a773b75a157995cb4276c1cbebac7fb 100644 (file)
--- a/drivers/gpu/drm/imagination/pvr_vm.c
+++ b/drivers/gpu/drm/imagination/pvr_vm.c
@@ -42,7 +42,7 @@ struct pvr_vm_context {
        /** @mmu_ctx: The context for binding to physical memory. */
        struct pvr_mmu_context *mmu_ctx;
 
-       /** @gpuva_mgr: GPUVA manager object associated with this context. */
+       /** @gpuvm_mgr: GPUVM object associated with this context. */
        struct drm_gpuvm gpuvm_mgr;
 
        /** @lock: Global lock on this VM. */

diff --git a/include/uapi/drm/pvr_drm.h b/include/uapi/drm/pvr_drm.h
index 1834375390c452de8c851c7f593d2082a962526e..ccf6c2112468f3f53b093bc298dac2bbbfd35e6e 100644 (file)
--- a/include/uapi/drm/pvr_drm.h
+++ b/include/uapi/drm/pvr_drm.h
@@ -741,20 +741,18 @@ enum drm_pvr_ctx_priority {
  */
 enum drm_pvr_ctx_type {
        /**
-        * @DRM_PVR_CTX_TYPE_RENDER: Render context. Use &struct
-        * drm_pvr_ioctl_create_render_context_args for context creation arguments.
+        * @DRM_PVR_CTX_TYPE_RENDER: Render context.
         */
        DRM_PVR_CTX_TYPE_RENDER = 0,
 
        /**
-        * @DRM_PVR_CTX_TYPE_COMPUTE: Compute context. Use &struct
-        * drm_pvr_ioctl_create_compute_context_args for context creation arguments.
+        * @DRM_PVR_CTX_TYPE_COMPUTE: Compute context.
         */
        DRM_PVR_CTX_TYPE_COMPUTE,
 
        /**
-        * @DRM_PVR_CTX_TYPE_TRANSFER_FRAG: Transfer context for fragment data masters. Use
-        * &struct drm_pvr_ioctl_create_transfer_context_args for context creation arguments.
+        * @DRM_PVR_CTX_TYPE_TRANSFER_FRAG: Transfer context for fragment data
+        * master.
         */
        DRM_PVR_CTX_TYPE_TRANSFER_FRAG,
 };