Merge "Add NDK API AThermal_getThermalHeadroomThresholds" into main

float AThermal_getThermalHeadroom(AThermalManager *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* manager,

                                          const AThermalHeadroomThreshold ** outThresholds,

                                          size_t* size) __INTRODUCED_IN(35);

#ifdef __cplusplus

}

#endif

/*

 * Copyright (C) 2023 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.

 */

#ifndef ANDROID_PRIVATE_NATIVE_THERMAL_H

#define ANDROID_PRIVATE_NATIVE_THERMAL_H

#include <stdint.h>

__BEGIN_DECLS

/**

 * For testing only.

 */

void AThermal_setIThermalServiceForTesting(void* iThermalService);

__END_DECLS

#endif // ANDROID_PRIVATE_NATIVE_THERMAL_H

 No newline at end of file