drivers/media/video/samsung/mali/common/pmm/mali_pmm.h

   1 /*
   2  * Copyright (C) 2010 ARM Limited. All rights reserved.
   3  *
   4  * This program is free software and is provided to you under the terms of the GNU General Public License version 2
   5  * as published by the Free Software Foundation, and any use by you of this program is subject to the terms of such GNU licence.
   6  *
   7  * A copy of the licence is included with the program, and can also be obtained from Free Software
   8  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
   9  */
  10
  11 /**
  12  * @file mali_pmm.h
  13  * Defines the power management module for the kernel device driver
  14  */
  15
  16 #ifndef __MALI_PMM_H__
  17 #define __MALI_PMM_H__
  18
  19 /* For mali_pmm_message_data and MALI_PMM_EVENT_UK_* defines */
  20 #include "mali_uk_types.h"
  21 #include "mali_platform.h"
  22
  23 #ifdef __cplusplus
  24 extern "C"
  25 {
  26 #endif
  27
  28 /**
  29  * @defgroup pmmapi Power Management Module APIs
  30  *
  31  * @{
  32  */
  33
  34 /** OS event tester */
  35 #define PMM_OS_TEST 0
  36
  37 /** @brief Compile option to turn on/off tracing */
  38 #define MALI_PMM_TRACE 0
  39 #define MALI_PMM_TRACE_SENT_EVENTS 0
  40
  41 /** @brief Compile option to switch between always on or job control PMM policy */
  42 #define MALI_PMM_ALWAYS_ON 0
  43
  44 /** @brief Overrides hardware PMU and uses software simulation instead
  45  *  @note This even stops intialization of PMU and cores being powered on at start up
  46  */
  47 #define MALI_PMM_NO_PMU 0
  48
  49 /** @brief PMM debug print to control debug message level */
  50 #define MALIPMM_DEBUG_PRINT(args) \
  51         MALI_DEBUG_PRINT(3, args)
  52
  53
  54 /** @brief power management event message identifiers.
  55  */
  56 /* These must match up with the pmm_trace_events & pmm_trace_events_internal
  57  * arrays
  58  */
  59 typedef enum mali_pmm_event_id
  60 {
  61         MALI_PMM_EVENT_OS_POWER_UP             =    0,   /**< OS power up event */
  62         MALI_PMM_EVENT_OS_POWER_DOWN           =    1,   /**< OS power down event */
  63         MALI_PMM_EVENT_JOB_SCHEDULED           =    2,   /**< Job scheduled to run event */
  64         MALI_PMM_EVENT_JOB_QUEUED              =    3,   /**< Job queued (but not run) event */
  65         MALI_PMM_EVENT_JOB_FINISHED            =    4,   /**< Job finished event */
  66         MALI_PMM_EVENT_TIMEOUT                 =    5,   /**< Time out timer has expired */
  67         MALI_PMM_EVENT_DVFS_PAUSE              =    6,   /**< Mali device pause event */
  68         MALI_PMM_EVENT_DVFS_RESUME             =    7,   /**< Mali device resume event */
  69
  70         MALI_PMM_EVENT_UKS                     =  200,   /**< Events from the user-side start here */
  71         MALI_PMM_EVENT_UK_EXAMPLE              =  _MALI_PMM_EVENT_UK_EXAMPLE,
  72
  73         MALI_PMM_EVENT_INTERNALS               = 1000,
  74         MALI_PMM_EVENT_INTERNAL_POWER_UP_ACK   = 1001,   /**< Internal power up acknowledgement */
  75         MALI_PMM_EVENT_INTERNAL_POWER_DOWN_ACK = 1002,   /**< Internal power down acknowledgment */
  76 } mali_pmm_event_id;
  77
  78
  79 /** @brief Use this when the power up/down callbacks do not need any OS data. */
  80 #define MALI_PMM_NO_OS_DATA 1
  81
  82
  83 /* @brief Geometry and pixel processor identifiers for the PMM
  84  *
  85  * @note these match the ARM Mali 400 PMU hardware definitions, apart from the "SYSTEM"
  86  */
  87 typedef enum mali_pmm_core_id_tag
  88 {
  89         MALI_PMM_CORE_SYSTEM = 0x00000000,          /**< All of the Mali hardware */
  90         MALI_PMM_CORE_GP     = 0x00000001,          /**< Mali GP2 */
  91         MALI_PMM_CORE_L2     = 0x00000002,          /**< Level 2 cache */
  92         MALI_PMM_CORE_PP0    = 0x00000004,          /**< Mali 200 pixel processor 0 */
  93         MALI_PMM_CORE_PP1    = 0x00000008,          /**< Mali 200 pixel processor 1 */
  94         MALI_PMM_CORE_PP2    = 0x00000010,          /**< Mali 200 pixel processor 2 */
  95         MALI_PMM_CORE_PP3    = 0x00000020,          /**< Mali 200 pixel processor 3 */
  96         MALI_PMM_CORE_PP_ALL = 0x0000003C           /**< Mali 200 pixel processors 0-3 */
  97 } mali_pmm_core_id;
  98
  99
 100 /* @brief PMM bitmask of mali_pmm_core_ids
 101  */
 102 typedef u32 mali_pmm_core_mask;
 103
 104 /* @brief PMM event timestamp type
 105  */
 106 typedef u32 mali_pmm_timestamp;
 107
 108 /** @brief power management event message struct
 109  */
 110 typedef struct _mali_pmm_message
 111 {
 112         mali_pmm_event_id id;               /**< event id */
 113         mali_pmm_message_data data;         /**< specific data associated with the event */
 114         mali_pmm_timestamp ts;              /**< timestamp the event was placed in the event queue */
 115 } mali_pmm_message_t;
 116
 117
 118
 119 /** @brief the state of the power management module.
 120  */
 121 /* These must match up with the pmm_trace_state array */
 122 typedef enum mali_pmm_state_tag
 123 {
 124         MALI_PMM_STATE_UNAVAILABLE       = 0,       /**< PMM is not available */
 125         MALI_PMM_STATE_SYSTEM_ON         = 1,       /**< All of the Mali hardware is on */
 126         MALI_PMM_STATE_SYSTEM_OFF        = 2,       /**< All of the Mali hardware is off */
 127         MALI_PMM_STATE_SYSTEM_TRANSITION = 3        /**< System is changing state */
 128 } mali_pmm_state;
 129
 130
 131 /** @brief a power management policy.
 132  */
 133 /* These must match up with the pmm_trace_policy array */
 134 typedef enum mali_pmm_policy_tag
 135 {
 136         MALI_PMM_POLICY_NONE        = 0,            /**< No policy */
 137         MALI_PMM_POLICY_ALWAYS_ON   = 1,            /**< Always on policy */
 138         MALI_PMM_POLICY_JOB_CONTROL = 2,            /**< Job control policy */
 139         MALI_PMM_POLICY_RUNTIME_JOB_CONTROL = 3     /**< Run time power management control policy */
 140 } mali_pmm_policy;
 141
 142 /** @brief Function to power up MALI
 143  *
 144  * @param cores core mask to power up the cores
 145  *
 146  * @return error code if MALI fails to power up
 147  */
 148 _mali_osk_errcode_t malipmm_powerup( u32 cores );
 149
 150 /** @brief Function to power down MALI
 151  *
 152  * @param cores core mask to power down the cores
 153  * @param The power mode to which MALI transitions
 154  *
 155  * @return error code if MALI fails to power down
 156  */
 157 _mali_osk_errcode_t malipmm_powerdown( u32 cores, mali_power_mode power_mode );
 158
 159 /** @brief Function to report to the OS when the power down has finished
 160  *
 161  * @param data The event message data that initiated the power down
 162  */
 163 void _mali_osk_pmm_power_down_done(mali_pmm_message_data data);
 164
 165 /** @brief Function to report to the OS when the power up has finished
 166  *
 167  * @param data The event message data that initiated the power up
 168  */
 169 void _mali_osk_pmm_power_up_done(mali_pmm_message_data data);
 170
 171 /** @brief Function to report that DVFS operation done
 172  *
 173  * @param data The event message data
 174  */
 175 void _mali_osk_pmm_dvfs_operation_done(mali_pmm_message_data data);
 176
 177 #if MALI_POWER_MGMT_TEST_SUITE
 178 /** @brief Function to notify power management events
 179  *
 180  * @param data The event message data
 181  */
 182 void _mali_osk_pmm_policy_events_notifications(mali_pmm_event_id event_id);
 183
 184 #endif
 185
 186 /** @brief Function to power up MALI
 187  *
 188  *  @note powers up the MALI during MALI device driver is unloaded
 189  */
 190 void malipmm_force_powerup( void );
 191
 192 /** @brief Function to report the OS that device is idle
 193  *
 194  *  @note inform the OS that device is idle
 195  */
 196 _mali_osk_errcode_t _mali_osk_pmm_dev_idle( void );
 197
 198 /** @brief Function to report the OS to activate device
 199  *
 200  * @note inform the os that device needs to be activated
 201  */
 202 int _mali_osk_pmm_dev_activate( void );
 203
 204 /** @brief Function to report OS PMM for cleanup
 205  *
 206  * @note Function to report OS PMM for cleanup
 207  */
 208 void _mali_osk_pmm_ospmm_cleanup( void );
 209
 210 /** @brief Queries the current state of the PMM software
 211  *
 212  * @note the state of the PMM can change after this call has returned
 213  *
 214  * @return the current PMM state value
 215  */
 216 mali_pmm_state _mali_pmm_state( void );
 217
 218 /** @brief List of cores that are registered with the PMM
 219  *
 220  * This will return the cores that have been currently registered with the PMM,
 221  * which is a bitwise OR of the mali_pmm_core_id_tags. A value of 0x0 means that
 222  * there are no cores registered.
 223  *
 224  * @note the list of cores can change after this call has returned
 225  *
 226  * @return a bit mask representing all the cores that have been registered with the PMM
 227  */
 228 mali_pmm_core_mask _mali_pmm_cores_list( void );
 229
 230 /** @brief List of cores that are powered up in the PMM
 231  *
 232  * This will return the subset of the cores that can be listed using mali_pmm_cores_
 233  * list, that have power. It is a bitwise OR of the mali_pmm_core_id_tags. A value of
 234  * 0x0 means that none of the cores registered are powered.
 235  *
 236  * @note the list of cores can change after this call has returned
 237  *
 238  * @return a bit mask representing all the cores that are powered up
 239  */
 240 mali_pmm_core_mask _mali_pmm_cores_powered( void );
 241
 242
 243 /** @brief List of power management policies that are supported by the PMM
 244  *
 245  * Given an empty array of policies - policy_list - which contains the number
 246  * of entries as specified by - policy_list_size, this function will populate
 247  * the list with the available policies. If the policy_list is too small for
 248  * all the policies then only policy_list_size entries will be returned. If the
 249  * policy_list is bigger than the number of available policies then, the extra
 250  * entries will be set to MALI_PMM_POLICY_NONE.
 251  * The function will also update available_policies with the number of policies
 252  * that are available, even if it exceeds the policy_list_size.
 253  * The function will succeed if all policies could be returned, else it will
 254  * fail if none or only a subset of policies could be returned.
 255  * The function will also fail if no policy_list is supplied, though
 256  * available_policies is optional.
 257  *
 258  * @note this is a STUB function and is not yet implemented
 259  *
 260  * @param policy_list_size is the number of policies that can be returned in
 261  * the policy_list argument
 262  * @param policy_list is an array of policies that should be populated with
 263  * the list of policies that are supported by the PMM
 264  * @param policies_available optional argument, if non-NULL will be set to the
 265  * number of policies available
 266  * @return _MALI_OSK_ERR_OK if the policies could be listed, or a suitable
 267  * _mali_osk_errcode_t otherwise.
 268  */
 269 _mali_osk_errcode_t _mali_pmm_list_policies(
 270                 u32 policy_list_size,
 271                 mali_pmm_policy *policy_list,
 272                 u32 *policies_available );
 273
 274 /** @brief Set the power management policy in the PMM
 275  *
 276  * Given a valid supported policy, this function will change the PMM to use
 277  * this new policy
 278  * The function will fail if the policy given is invalid or unsupported.
 279  *
 280  * @note this is a STUB function and is not yet implemented
 281  *
 282  * @param policy the new policy to be set
 283  * @return _MALI_OSK_ERR_OK if the policy could be set, or a suitable
 284  * _mali_osk_errcode_t otherwise.
 285  */
 286 _mali_osk_errcode_t _mali_pmm_set_policy( mali_pmm_policy policy );
 287
 288 /** @brief Get the current power management policy in the PMM
 289  *
 290  * Given a pointer to a policy data type, this function will return the current
 291  * policy that is in effect for the PMM. This maybe out of date if there is a
 292  * pending set policy call that has not been serviced.
 293  * The function will fail if the policy given is NULL.
 294  *
 295  * @note the policy of the PMM can change after this call has returned
 296  *
 297  * @param policy a pointer to a policy that can be updated to the current
 298  * policy
 299  * @return _MALI_OSK_ERR_OK if the policy could be returned, or a suitable
 300  * _mali_osk_errcode_t otherwise.
 301  */
 302 _mali_osk_errcode_t _mali_pmm_get_policy( mali_pmm_policy *policy );
 303
 304 #if MALI_PMM_TRACE
 305
 306 /** @brief Indicates when a hardware state change occurs in the PMM
 307  *
 308  * @param old a mask of the cores indicating the previous state of the cores
 309  * @param newstate a mask of the cores indicating the new current state of the cores
 310  */
 311 void _mali_pmm_trace_hardware_change( mali_pmm_core_mask old, mali_pmm_core_mask newstate );
 312
 313 /** @brief Indicates when a state change occurs in the PMM
 314  *
 315  * @param old the previous state for the PMM
 316  * @param newstate the new current state of the PMM
 317  */
 318 void _mali_pmm_trace_state_change( mali_pmm_state old, mali_pmm_state newstate );
 319
 320 /** @brief Indicates when a policy change occurs in the PMM
 321  *
 322  * @param old the previous policy for the PMM
 323  * @param newpolicy the new current policy of the PMM
 324  */
 325 void _mali_pmm_trace_policy_change( mali_pmm_policy old, mali_pmm_policy newpolicy );
 326
 327 /** @brief Records when an event message is read by the event system
 328  *
 329  * @param event the message details
 330  * @param received MALI_TRUE when the message is received by the PMM, else it is being sent
 331  */
 332 void _mali_pmm_trace_event_message( mali_pmm_message_t *event, mali_bool received );
 333
 334 #endif /* MALI_PMM_TRACE */
 335
 336 /** @brief Dumps the current state of OS PMM thread
 337  */
 338 #if MALI_STATE_TRACKING
 339 u32 mali_pmm_dump_os_thread_state( char *buf, u32 size );
 340 #endif /* MALI_STATE_TRACKING */
 341
 342 /** @} */ /* end group pmmapi */
 343
 344 #ifdef __cplusplus
 345 }
 346 #endif
 347
 348 #endif /* __MALI_PMM_H__ */