include/android/thermal.h

/*
 * Copyright (C) 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup Thermal
 * @{
 */

/**
 * @file thermal.h
 */

#ifndef _ANDROID_THERMAL_H
#define _ANDROID_THERMAL_H

#include <sys/cdefs.h>

/******************************************************************
 *
 * IMPORTANT NOTICE:
 *
 *   This file is part of Android's set of stable system headers
 *   exposed by the Android NDK (Native Development Kit).
 *
 *   Third-party source AND binary code relies on the definitions
 *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
 *
 *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
 *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
 *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
 *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
 */

/*
 * Structures and functions to access thermal status and register/unregister
 * thermal status listener in native code.
 */

#include <stdint.h>
#include <sys/types.h>

#if !defined(__INTRODUCED_IN)
#define __INTRODUCED_IN(__api_level) /* nothing */
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Thermal status used in function {@link AThermal_getCurrentThermalStatus} and
 * {@link AThermal_StatusCallback}.
 */
enum AThermalStatus {
    /** Error in thermal status. */
    ATHERMAL_STATUS_ERROR = -1,
    /** Not under throttling. */
    ATHERMAL_STATUS_NONE = 0,
    /** Light throttling where UX is not impacted. */
    ATHERMAL_STATUS_LIGHT = 1,
    /** Moderate throttling where UX is not largely impacted. */
    ATHERMAL_STATUS_MODERATE = 2,
    /** Severe throttling where UX is largely impacted. */
    ATHERMAL_STATUS_SEVERE = 3,
    /** Platform has done everything to reduce power. */
    ATHERMAL_STATUS_CRITICAL = 4,
    /**
     * Key components in platform are shutting down due to thermal condition.
     * Device functionalities will be limited.
     */
    ATHERMAL_STATUS_EMERGENCY = 5,
    /** Need shutdown immediately. */
    ATHERMAL_STATUS_SHUTDOWN = 6,
};

/**
 * An opaque type representing a handle to a thermal manager.
 * An instance of thermal manager must be acquired prior to
 * using thermal status APIs and must be released after use.
 *
 * <p>To use:<ul>
 *    <li>Create a new thermal manager instance by calling the
 *        {@link AThermal_acquireManager} function.</li>
 *    <li>Get current thermal status with
 *        {@link AThermal_getCurrentThermalStatus}.</li>
 *    <li>Register a thermal status listener with
 *        {@link AThermal_registerThermalStatusListener}.</li>
 *    <li>Unregister a thermal status listener with
 *        {@link AThermal_unregisterThermalStatusListener}.</li>
 *    <li>Release the thermal manager instance with
 *        {@link AThermal_releaseManager}.</li></ul></p>
 *
 */
typedef struct AThermalManager AThermalManager;

/**
 * Prototype of the function that is called when thermal status changes.
 * It's passed the updated thermal status as parameter, as well as the
 * pointer provided by the client that registered a callback.
 */
typedef void (*AThermal_StatusCallback)(void* _Nullable data, AThermalStatus status);

/**
  * Acquire an instance of the thermal manager. This must be freed using
  * {@link AThermal_releaseManager}.
  *
  * Available since API level 30.
  *
  * @return manager instance on success, nullptr on failure.
  */
AThermalManager* _Nonnull AThermal_acquireManager() __INTRODUCED_IN(30);

/**
 * Release the thermal manager pointer acquired via
 * {@link AThermal_acquireManager}.
 *
 * Available since API level 30.
 *
 * @param manager The manager to be released.
 */
void AThermal_releaseManager(AThermalManager* _Nonnull manager) __INTRODUCED_IN(30);

/**
  * Gets the current thermal status.
  *
  * Available since API level 30.
  *
  * @param manager The manager instance to use to query the thermal status.
  * Acquired via {@link AThermal_acquireManager}.
  *
  * @return current thermal status, ATHERMAL_STATUS_ERROR on failure.
  */
AThermalStatus
AThermal_getCurrentThermalStatus(AThermalManager* _Nonnull manager) __INTRODUCED_IN(30);

/**
 * Register the thermal status listener for thermal status change.
 *
 * Available since API level 30.
 *
 * @param manager The manager instance to use to register.
 * Acquired via {@link AThermal_acquireManager}.
 * @param callback The callback function to be called when thermal status updated.
 * @param data The data pointer to be passed when callback is called.
 *
 * @return 0 on success
 *         EINVAL if the listener and data pointer were previously added and not removed.
 *         EPERM if the required permission is not held.
 *         EPIPE if communication with the system service has failed.
 */
int AThermal_registerThermalStatusListener(AThermalManager* _Nonnull manager,
                                           AThermal_StatusCallback _Nullable callback,
                                           void* _Nullable data) __INTRODUCED_IN(30);

/**
 * Unregister the thermal status listener previously resgistered.
 *
 * Available since API level 30.
 *
 * @param manager The manager instance to use to unregister.
 * Acquired via {@link AThermal_acquireManager}.
 * @param callback The callback function to be called when thermal status updated.
 * @param data The data pointer to be passed when callback is called.
 *
 * @return 0 on success
 *         EINVAL if the listener and data pointer were not previously added.
 *         EPERM if the required permission is not held.
 *         EPIPE if communication with the system service has failed.
 */
int AThermal_unregisterThermalStatusListener(AThermalManager* _Nonnull manager,
                                             AThermal_StatusCallback _Nullable callback,
                                             void* _Nullable data) __INTRODUCED_IN(30);

/**
 * Provides an estimate of how much thermal headroom the device currently has before
 * hitting severe throttling.
 *
 * Note that this only attempts to track the headroom of slow-moving sensors, such as
 * the skin temperature sensor. This means that there is no benefit to calling this function
 * more frequently than about once per second, and attempted to call significantly
 * more frequently may result in the function returning `NaN`.
 *
 * In addition, in order to be able to provide an accurate forecast, the system does
 * not attempt to forecast until it has multiple temperature samples from which to
 * extrapolate. This should only take a few seconds from the time of the first call,
 * but during this time, no forecasting will occur, and the current headroom will be
 * returned regardless of the value of `forecastSeconds`.
 *
 * The value returned is a non-negative float that represents how much of the thermal envelope
 * is in use (or is forecasted to be in use). A value of 1.0 indicates that the device is
 * (or will be) throttled at {@link #ATHERMAL_STATUS_SEVERE}. Such throttling can affect the
 * CPU, GPU, and other subsystems. Values may exceed 1.0, but there is no implied mapping
 * to specific thermal levels beyond that point. This means that values greater than 1.0
 * may correspond to {@link #ATHERMAL_STATUS_SEVERE}, but may also represent heavier throttling.
 *
 * A value of 0.0 corresponds to a fixed distance from 1.0, but does not correspond to any
 * particular thermal status or temperature. Values on (0.0, 1.0] may be expected to scale
 * linearly with temperature, though temperature changes over time are typically not linear.
 * Negative values will be clamped to 0.0 before returning.
 *
 * Available since API level 31.
 *
 * @param manager The manager instance to use.
 *                Acquired via {@link AThermal_acquireManager}.
 * @param forecastSeconds how many seconds into the future to forecast. Given that device
 *                        conditions may change at any time, forecasts from further in the
 *                        future will likely be less accurate than forecasts in the near future.
 * @return a value greater than equal to 0.0, where 1.0 indicates the SEVERE throttling threshold,
 *         as described above. Returns NaN if the device does not support this functionality or
 *         if this function is called significantly faster than once per second.
  */
float AThermal_getThermalHeadroom(AThermalManager* _Nonnull manager,
                                  int forecastSeconds) __INTRODUCED_IN(31);

/**
 * This struct defines an instance of headroom threshold value and its status.
 * <p>
 * The value should be monotonically non-decreasing as the thermal status increases.
 * For {@link ATHERMAL_STATUS_SEVERE}, its headroom threshold is guaranteed to
 * be 1.0f. For status below severe status, the value should be lower or equal
 * to 1.0f, and for status above severe, the value should be larger or equal to 1.0f.
 * <p>
 * Also see {@link AThermal_getThermalHeadroom} for explanation on headroom, and
 * {@link AThermal_getThermalHeadroomThresholds} for how to use this.
 */
struct AThermalHeadroomThreshold {
    float headroom;
    AThermalStatus thermalStatus;
};

/**
 * Gets the thermal headroom thresholds for all available thermal status.
 *
 * A thermal status will only exist in output if the device manufacturer has the
 * corresponding threshold defined for at least one of its slow-moving skin temperature
 * sensors. If it's set, one should also expect to get it from
 * {@link #AThermal_getCurrentThermalStatus} or {@link AThermal_StatusCallback}.
 * <p>
 * The headroom threshold is used to interpret the possible thermal throttling status based on
 * the headroom prediction. For example, if the headroom threshold for
 * {@link ATHERMAL_STATUS_LIGHT} is 0.7, and a headroom prediction in 10s returns 0.75
 * (or {@code AThermal_getThermalHeadroom(10)=0.75}), one can expect that in 10 seconds the system
 * could be in lightly throttled state if the workload remains the same. The app can consider
 * taking actions according to the nearest throttling status the difference between the headroom and
 * the threshold.
 * <p>
 * For new devices it's guaranteed to have a single sensor, but for older devices with multiple
 * sensors reporting different threshold values, the minimum threshold is taken to be conservative
 * on predictions. Thus, when reading real-time headroom, it's not guaranteed that a real-time value
 * of 0.75 (or {@code AThermal_getThermalHeadroom(0)}=0.75) exceeding the threshold of 0.7 above
 * will always come with lightly throttled state
 * (or {@code AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_LIGHT}) but it can be lower
 * (or {@code AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_NONE}).
 * While it's always guaranteed that the device won't be throttled heavier than the unmet
 * threshold's state, so a real-time headroom of 0.75 will never come with
 * {@link #ATHERMAL_STATUS_MODERATE} but always lower, and 0.65 will never come with
 * {@link ATHERMAL_STATUS_LIGHT} but {@link #ATHERMAL_STATUS_NONE}.
 * <p>
 * The returned list of thresholds is cached on first successful query and owned by the thermal
 * manager, which will not change between calls to this function. The caller should only need to
 * free the manager with {@link AThermal_releaseManager}.
 *
 * @param manager The manager instance to use.
 *                Acquired via {@link AThermal_acquireManager}.
 * @param outThresholds non-null output pointer to null AThermalHeadroomThreshold pointer, which
 *                will be set to the cached array of thresholds if thermal thresholds are supported
 *                by the system or device, otherwise nullptr or unmodified.
 * @param size non-null output pointer whose value will be set to the size of the threshold array
 *             or 0 if it's not supported.
 * @return 0 on success
 *         EINVAL if outThresholds or size_t is nullptr, or *outThresholds is not nullptr.
 *         EPIPE if communication with the system service has failed.
 *         ENOSYS if the feature is disabled by the current system.
 */
int AThermal_getThermalHeadroomThresholds(AThermalManager* _Nonnull manager,
                                          const AThermalHeadroomThreshold* _Nonnull
                                          * _Nullable outThresholds,
                                          size_t* _Nonnull size) __INTRODUCED_IN(35);

#ifdef __cplusplus
}
#endif

#endif // _ANDROID_THERMAL_H

/** @} */