1 /* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup Thermal 19 * @{ 20 */ 21 22 /** 23 * @file thermal.h 24 */ 25 26 #ifndef _ANDROID_THERMAL_H 27 #define _ANDROID_THERMAL_H 28 29 #include <sys/cdefs.h> 30 31 /****************************************************************** 32 * 33 * IMPORTANT NOTICE: 34 * 35 * This file is part of Android's set of stable system headers 36 * exposed by the Android NDK (Native Development Kit). 37 * 38 * Third-party source AND binary code relies on the definitions 39 * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 40 * 41 * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 42 * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 43 * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 44 * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 45 */ 46 47 /* 48 * Structures and functions to access thermal status and register/unregister 49 * thermal status listener in native code. 50 */ 51 52 #include <stdint.h> 53 #include <sys/types.h> 54 55 #if !defined(__INTRODUCED_IN) 56 #define __INTRODUCED_IN(30) /* Introduced in API level 30 */ 57 #endif 58 59 #ifdef __cplusplus 60 extern "C" { 61 #endif 62 63 #if __ANDROID_API__ >= 30 64 65 enum AThermalStatus { 66 /** Error in thermal status. */ 67 ATHERMAL_STATUS_ERROR = -1, 68 /** Not under throttling. */ 69 ATHERMAL_STATUS_NONE = 0, 70 /** Light throttling where UX is not impacted. */ 71 ATHERMAL_STATUS_LIGHT = 1, 72 /** Moderate throttling where UX is not largely impacted. */ 73 ATHERMAL_STATUS_MODERATE = 2, 74 /** Severe throttling where UX is largely impacted. */ 75 ATHERMAL_STATUS_SEVERE = 3, 76 /** Platform has done everything to reduce power. */ 77 ATHERMAL_STATUS_CRITICAL = 4, 78 /** 79 * Key components in platform are shutting down due to thermal condition. 80 * Device functionalities will be limited. 81 */ 82 ATHERMAL_STATUS_EMERGENCY = 5, 83 /** Need shutdown immediately. */ 84 ATHERMAL_STATUS_SHUTDOWN = 6, 85 }; 86 87 /** 88 * An opaque type representing a handle to a thermal manager. 89 * An instance of thermal manager must be acquired prior to 90 * using thermal status APIs and must be released after use. 91 * 92 * <p>To use:<ul> 93 * <li>Create a new thermal manager instance by calling the 94 * {@link AThermal_acquireManager} function.</li> 95 * <li>Get current thermal status with 96 * {@link AThermal_getCurrentThermalStatus}.</li> 97 * <li>Register a thermal status listener with 98 * {@link AThermal_registerThermalStatusListener}.</li> 99 * <li>Unregister a thermal status listener with 100 * {@link AThermal_unregisterThermalStatusListener}.</li> 101 * <li>Release the thermal manager instance with 102 * {@link AThermal_releaseManager}.</li></ul></p> 103 * 104 */ 105 typedef struct AThermalManager AThermalManager; 106 107 /** 108 * Prototype of the function that is called when thermal status changes. 109 * It's passed the updated thermal status as parameter, as well as the 110 * pointer provided by the client that registered a callback. 111 */ 112 typedef void (*AThermal_StatusCallback)(void *data, AThermalStatus status); 113 114 /** 115 * Acquire an instance of the thermal manager. This must be freed using 116 * {@link AThermal_releaseManager}. 117 * 118 * @return manager instance on success, nullptr on failure. 119 */ 120 AThermalManager* AThermal_acquireManager(); 121 122 /** 123 * Release the thermal manager pointer acquired via 124 * {@link AThermal_acquireManager}. 125 * 126 * @param manager The manager to be released. 127 * 128 */ 129 void AThermal_releaseManager(AThermalManager *manager); 130 131 /** 132 * Gets the current thermal status. 133 * 134 * @param manager The manager instance to use to query the thermal status. 135 * Acquired via {@link AThermal_acquireManager}. 136 * 137 * @return current thermal status, ATHERMAL_STATUS_ERROR on failure. 138 */ 139 AThermalStatus AThermal_getCurrentThermalStatus(AThermalManager *manager); 140 141 /** 142 * Register the thermal status listener for thermal status change. 143 * 144 * @param manager The manager instance to use to register. 145 * Acquired via {@link AThermal_acquireManager}. 146 * @param callback The callback function to be called when thermal status updated. 147 * @param data The data pointer to be passed when callback is called. 148 * 149 * @return 0 on success 150 * EINVAL if the listener and data pointer were previously added and not removed. 151 * EPERM if the required permission is not held. 152 * EPIPE if communication with the system service has failed. 153 */ 154 int AThermal_registerThermalStatusListener(AThermalManager *manager, 155 AThermal_StatusCallback callback, void *data); 156 157 /** 158 * Unregister the thermal status listener previously resgistered. 159 * 160 * @param manager The manager instance to use to unregister. 161 * Acquired via {@link AThermal_acquireManager}. 162 * @param callback The callback function to be called when thermal status updated. 163 * @param data The data pointer to be passed when callback is called. 164 * 165 * @return 0 on success 166 * EINVAL if the listener and data pointer were not previously added. 167 * EPERM if the required permission is not held. 168 * EPIPE if communication with the system service has failed. 169 */ 170 int AThermal_unregisterThermalStatusListener(AThermalManager *manager, 171 AThermal_StatusCallback callback, void *data); 172 173 174 #endif // __ANDROID_API__ >= 30 175 176 #ifdef __cplusplus 177 } 178 #endif 179 180 #endif // _ANDROID_THERMAL_H 181 182 /** @} */ 183