Merge r36p0 from upstream into android-gs-pixel-5.10-gs101

Bug: 220942030
Test: boot to Home, Camera, Video, Chrome
Signed-off-by: Siddharth Kapoor <ksiddharth@google.com>
Change-Id: I8cf3a6243b092a05299acf956f5293facd1ed3cc

1 files changed, 40 insertions, 31 deletions

diff --git a/mali_kbase/mali_kbase_pm.h b/mali_kbase/mali_kbase_pm.h
index f7d0b7e..7252bc7 100644
--- a/mali_kbase/mali_kbase_pm.h
+++ b/mali_kbase/mali_kbase_pm.h
@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
 /*
  *
- * (C) COPYRIGHT 2010-2021 ARM Limited. All rights reserved.
+ * (C) COPYRIGHT 2010-2022 ARM Limited. All rights reserved.
  *
  * This program is free software and is provided to you under the terms of the
  * GNU General Public License version 2 as published by the Free Software
@@ -20,7 +20,7 @@
  */
 
 /**
- * Power management API definitions
+ * DOC: Power management API definitions
  */
 
 #ifndef _KBASE_PM_H_
@@ -39,29 +39,32 @@
 #define PM_NO_RESET          0x04
 #endif
 
-/** Initialize the power management framework.
- *
- * Must be called before any other power management function
+/**
+ * kbase_pm_init - Initialize the power management framework.
  *
- * @param kbdev The kbase device structure for the device
+ * @kbdev: The kbase device structure for the device
  *              (must be a valid pointer)
  *
- * @return 0 if the power management framework was successfully initialized.
+ * Must be called before any other power management function
+ *
+ * Return: 0 if the power management framework was successfully initialized.
  */
 int kbase_pm_init(struct kbase_device *kbdev);
 
-/** Power up GPU after all modules have been initialized and interrupt handlers installed.
- *
- * @param kbdev     The kbase device structure for the device (must be a valid pointer)
+/**
+ * kbase_pm_powerup - Power up GPU after all modules have been initialized
+ *                    and interrupt handlers installed.
  *
- * @param flags     Flags to pass on to kbase_pm_init_hw
+ * @kbdev:     The kbase device structure for the device (must be a valid pointer)
+ * @flags:     Flags to pass on to kbase_pm_init_hw
  *
- * @return 0 if powerup was successful.
+ * Return: 0 if powerup was successful.
  */
 int kbase_pm_powerup(struct kbase_device *kbdev, unsigned int flags);
 
 /**
- * Halt the power management framework.
+ * kbase_pm_halt - Halt the power management framework.
+ *
  * @kbdev: The kbase device structure for the device (must be a valid pointer)
  *
  * Should ensure that no new interrupts are generated,
@@ -71,16 +74,20 @@ int kbase_pm_powerup(struct kbase_device *kbdev, unsigned int flags);
  */
 void kbase_pm_halt(struct kbase_device *kbdev);
 
-/** Terminate the power management framework.
+/**
+ * kbase_pm_term - Terminate the power management framework.
+ *
+ * @kbdev:     The kbase device structure for the device (must be a valid pointer)
  *
  * No power management functions may be called after this
  * (except @ref kbase_pm_init)
- *
- * @param kbdev     The kbase device structure for the device (must be a valid pointer)
  */
 void kbase_pm_term(struct kbase_device *kbdev);
 
-/** Increment the count of active contexts.
+/**
+ * kbase_pm_context_active - Increment the count of active contexts.
+ *
+ * @kbdev:     The kbase device structure for the device (must be a valid pointer)
  *
  * This function should be called when a context is about to submit a job.
  * It informs the active power policy that the GPU is going to be in use shortly
@@ -94,8 +101,6 @@ void kbase_pm_term(struct kbase_device *kbdev);
  * @note a Suspend is only visible to Kernel threads; user-space threads in a
  * syscall cannot witness a suspend, because they are frozen before the suspend
  * begins.
- *
- * @param kbdev     The kbase device structure for the device (must be a valid pointer)
  */
 void kbase_pm_context_active(struct kbase_device *kbdev);
 
@@ -123,7 +128,11 @@ enum kbase_pm_suspend_handler {
 #endif /* CONFIG_MALI_ARBITER_SUPPORT */
 };
 
-/** Suspend 'safe' variant of kbase_pm_context_active()
+/**
+ * kbase_pm_context_active_handle_suspend - Suspend 'safe' variant of kbase_pm_context_active()
+ *
+ * @kbdev:     The kbase device structure for the device (must be a valid pointer)
+ * @suspend_handler: The handler code for how to handle a suspend that might occur
  *
  * If a suspend is in progress, this allows for various different ways of
  * handling the suspend. Refer to @ref enum kbase_pm_suspend_handler for details.
@@ -133,20 +142,18 @@ enum kbase_pm_suspend_handler {
  * indicates a failure, the caller must abort whatever operation it was
  * attempting, and potentially queue it up for after the OS has resumed.
  *
- * @param kbdev     The kbase device structure for the device (must be a valid pointer)
- * @param suspend_handler The handler code for how to handle a suspend that might occur
- * @return zero     Indicates success
- * @return non-zero Indicates failure due to the system being suspending/suspended.
+ * Return: 0 on success, non-zero othrewise.
  */
 int kbase_pm_context_active_handle_suspend(struct kbase_device *kbdev, enum kbase_pm_suspend_handler suspend_handler);
 
-/** Decrement the reference count of active contexts.
+/**
+ * kbase_pm_context_idle - Decrement the reference count of active contexts.
+ *
+ * @kbdev:     The kbase device structure for the device (must be a valid pointer)
  *
  * This function should be called when a context becomes idle.
  * After this call the GPU may be turned off by the power policy so the calling
  * code should ensure that it does not access the GPU's registers.
- *
- * @param kbdev     The kbase device structure for the device (must be a valid pointer)
  */
 void kbase_pm_context_idle(struct kbase_device *kbdev);
 
@@ -155,8 +162,9 @@ void kbase_pm_context_idle(struct kbase_device *kbdev);
  */
 
 /**
- * Suspend the GPU and prevent any further register accesses to it from Kernel
- * threads.
+ * kbase_pm_suspend - Suspend the GPU and prevent any further register accesses
+ *                    to it from Kernel threads.
+ *
  * @kbdev: The kbase device structure for the device (must be a valid pointer)
  *
  * This is called in response to an OS suspend event, and calls into the various
@@ -171,8 +179,9 @@ void kbase_pm_context_idle(struct kbase_device *kbdev);
 int kbase_pm_suspend(struct kbase_device *kbdev);
 
 /**
- * Resume the GPU, allow register accesses to it, and resume running atoms on
- * the GPU.
+ * kbase_pm_resume - Resume the GPU, allow register accesses to it,
+ *                   and resume running atoms on the GPU.
+ *
  * @kbdev: The kbase device structure for the device (must be a valid pointer)
  *
  * This is called in response to an OS resume event, and calls into the various