Thermal Sensor

Supported ICs[ RTL8720E ][ RTL8710E ][ RTL8726E ][ RTL8713E ][ RTL8730E ][ RTL8721F ]

Introduction

SoC has integrated a thermal sensor, which can be used to detect and monitor the real-time temperature inside the chip. It has the following features:

Measurement range: -40°C ~ 125°C
Accuracy: ±1°C (typical), ±3°C (worst case)
Provides low-temperature warning, high-temperature warning and over-temperature protection
Provides thermal enable and over-temperature protection enable write access control
Configurable reboot time interval
Records maximum and minimum temperature

Temperature Protection

The temperature protection mechanism is an important feature provided by the thermal sensor, and is implemented as follows:

When the temperature exceeds the configured high-temperature threshold, an interrupt is sent to the CPU, allowing it to decrease its frequency.
When the temperature drops below the configured low-temperature threshold, an interrupt is sent to the CPU, allowing it to increase its frequency.
When the temperature exceeds the configured over-temperature protection threshold, the hardware will automatically shut down the power for over-temperature protection.

Note

By default, the SDK does not automatically adjust the CPU frequency based on the temperature detected by the thermal sensor. If users need to use this feature, please call thermal related APIs to configure the temperature threshold according to the actual application conditions.
After power-off caused by over-temperature protection, the chip will automatically reboot in a predefined time interval and BOOT REASON: THM will be displayed in the boot log.

Low Power Mode

When the chip enters deep sleep mode or PG sleep mode, power domain of the thermal sensor is shut down and thermal sensor cannot work.

When the chip enters CG sleep mode, the SDK will disable the thermal sensor by default, making it unable to function as well.

Note

Once the chip enters deep sleep mode or PG sleep mode, the records of maximum and minimum temperature will be lost.
The SDK will enable the thermal sensor again by default after the chip exits CG sleep mode.

Usage

The steps of using thermal to get current temperature are as below:

Set default parameters.

After that, thermal threshold, down sample rate and other parameters can be modified in TM_InitStruct() if needed.
```
TM_StructInit(TM_InitTypeDef *TM_InitStruct);
```

Initialize the thermal.

TM_Init(TM_InitTypeDef *TM_InitStruct);

Configure interrupt and register interrupt callback function.

InterruptRegister((IRQ_FUN)TMIrqHandler, TmIrqNum[CPUID], NULL, 10);
InterruptEn(TmIrqNum[CPUID], 10);

Enable the thermal.
```
TM_Cmd(ENABLE);
```

Enable the thermal interrupt.

TM_INTConfig(TM_BIT_IMR_TM_HIGH_WT | TM_BIT_IMR_TM_LOW_WT, ENABLE);

Raw API

THERMAL Exported Types

struct TM_InitTypeDef

Thermal Init Structure Definition.

Public Members

u8 TM_DownSampRate: Specifies thermal decimation filter down sample rate. This parameter can be a value of TM Down Sample Rate

u8 TM_AdcClkDiv: Specifies thermal ADC clock divider. This parameter can be a value of TM ADC CLK Divider

u16 TM_HighProtectThreshold: Specifies thermal high protection threshold. When the measured temperature is greater than or equal to this value, HW power down protection is triggered. This parameter only between 0x046 and 0x08C is valid.

u16 TM_HighWarnThreshold: Specifies thermal high warning threshold. The high warning interrupt is generated when the measured temperature is greater than or equal to this value, and less than TM_HighProtectThreshold, and tm_highcmp_wt_en=1, imr_tm_high_wt=1.

u16 TM_LowWarnThreshold: Specifies thermal low warning threshold. The low warning interrupt is generated when the measured temperature is less than or equal to this value, and tm_lowcmp_wt_en=1, imr_tm_low_wt=1.

u8 TM_TimePeriod: Specifies timer period between HW power down and restart. When the measured temperature is greater than or equal to TM_HighProtectThreshold, HW auto power down, the system will auto restart after this value time period

THERMAL Exported Constants

TM ADC CLK Divider

/* ADC clock divider: divide source clock by 256. */
#define TM_ADC_CLK_DIV_256 ((u8)0x00)

/* ADC clock divider: divide source clock by 128. */
#define TM_ADC_CLK_DIV_128 ((u8)0x01)

/* Checks if parameter is a valid ADC clock divider. */
#define IS_TM_ADC_CLK_DIV (((div) == TM_ADC_CLK_DIV_256) || \
    ((div) == TM_ADC_CLK_DIV_128))

TM Decimal Out

/* Extracts decimal part (bits[9:0]) from raw temperature output. */
#define TEMP_DECIMAL_OUT ((u32)((x) & 0x000003FF))

TM Down Sample Rate

/* Down sample rate: 128 (decimation filter OSR = 128). */
#define TM_DSR_128 ((u8)0x00)

/* Down sample rate: 256 (decimation filter OSR = 256). */
#define TM_DSR_256 ((u8)0x01)

/* Down sample rate: 512 (decimation filter OSR = 512). */
#define TM_DSR_512 ((u8)0x02)

/* Down sample rate: 1024 (decimation filter OSR = 1024). */
#define TM_DSR_1024 ((u8)0x03)

/* Checks if parameter is a valid down sample rate. */
#define IS_TM_DOWN_SAMPLE_RATE (((sel) == TM_DSR_128) || \
    ((sel) == TM_DSR_256) || \
    ((sel) == TM_DSR_512) || \
    ((sel) == TM_DSR_1024))

TM Programme Password

/* Password value required to program thermal meter registers. */
#define TM_PROG_PWR (0x69)

TM Temp Define

/* Minimum encoded value for a positive temperature reading. */
#define TM_POSITIVE_MIN ((u32)0x00000)

/* Maximum encoded value for a positive temperature reading. */
#define TM_POSITIVE_MAX ((u32)0x3FFFF)

/* Minimum encoded value for a negative temperature reading. */
#define TM_NEGATIVE_MIN ((u32)0x40000)

/* Maximum encoded value for a negative temperature reading. */
#define TM_NEGATIVE_MAX ((u32)0x7FFFF)

/* Encoded value indicating an invalid/unavailable temperature result. */
#define TM_INVALID_VALUE ((u32)0x80000)

/* Checks if raw temperature value represents a positive temperature. */
#define TM_IS_POSITIVE (((x) >= TM_POSITIVE_MIN) && ((x) <= TM_POSITIVE_MAX))

/* Checks if raw temperature value represents a negative temperature. */
#define TM_IS_NEGATIVE (((x) >= TM_NEGATIVE_MIN) && ((x) <= TM_NEGATIVE_MAX))

TM Calibration Value

RTL8720E:

Not supported.

RTL8721F:

/* Default calibration gain value for thermal meter. */
#define TM_CALIB_GAIN ((u32)0x834D000)

/* Default calibration offset value for thermal meter. */
#define TM_CALIB_OFFSET ((u32)0x370E00)

THERMAL Exported Functions

void TM_Cmd(u32 NewState)

Enable or disable the thermal peripheral.

Parameters:

NewState – New state of the thermal peripheral. This parameter can be ENABLE or DISABLE.

float TM_GetCdegree(u32 Data)

Get Celsius Degree.

Parameters:

Data – TM_RESULT(Binary complement form)

Returns:

Temperature value of float type.

float TM_GetFdegree(u32 Data)

Get Fahrenheit Degree.

Parameters:

Data – TM_RESULT(Binary complement form)

Returns:

Temperature value of float type.

u32 TM_GetISR(void)

Get thermal interrupt status.

Returns:: Current interrupt status, with each bit defined in TM_INTR_STS.

u32 TM_GetMaxTemp(void)

Get thermal max temperature result.

Returns:

The measured max temperature:

TM_INVALID_VALUE: invalid value
[0, TM_INVALID_VALUE): measured max temperature

u32 TM_GetMinTemp(void)

Get thermal min temperature result.

Returns:

The measured min temperature:

TM_INVALID_VALUE: invalid value
[0, TM_INVALID_VALUE): measured min temperature

u32 TM_GetPowOnTemp(void)

Get thermal power on temperature result.

Returns:

The measured power on temperature:

TM_INVALID_VALUE: invalid value
[0, TM_INVALID_VALUE): measured power on temperature

u32 TM_GetTempResult(void)

Get thermal temperature result.

Returns:

The measured temperature:

TM_INVALID_VALUE: invalid value
[0, TM_INVALID_VALUE): measured temperature

void TM_HighPtConfig(u16 TM_HighPtThre, u32 NewState)

Configure over-temp protect threshold for comparison with TEMP_OUT.

Parameters:

TM_HighPtThre – When TEMP_OUT > TM_HighPtThre, an AON reset is triggered.
NewState – New state of the thermal over-temp protect comparison. This parameter can be ENABLE or DISABLE.

void TM_HighWtConfig(u16 TM_HighWtThre, u32 NewState)

Configure over-temp warning threshold for comparison with TEMP_OUT.

Parameters:

TM_HighWtThre – When TM_HighWtThre <= TEMP_OUT < TM_HighPtThre, the ISR_TM_HIGH interrupt flag is set.
NewState – New state of the thermal over-temp warning comparison. This parameter can be ENABLE or DISABLE.

Note

Only values greater than 0 are supported.

void TM_INTClear(void): Clear all the thermal interrupt pending bits.

void TM_INTClearPendingBits(u32 TM_IT)

Clear the thermal interrupt pending bits.

Parameters:

TM_IT – Specifies the pending bit to clear. This parameter can be one or combinations of bits in TM_INTR_STS.

void TM_INTConfig(u32 TM_IT, u32 NewState)

Enable or disable the thermal interrupt bits.

Parameters:

TM_IT – Specifies the thermal interrupt to be configured. This parameter can be one or combinations of bits in TM_INTR_CTRL.
NewState – ENABLE or DISABLE.

void TM_Init(TM_InitTypeDef *TM_InitStruct)

Initialize the thermal according to the specified parameters in TM_InitStruct.

Parameters:

TM_InitStruct – Pointer to a TM_InitTypeDef structure that contains the configuration information for the thermal peripheral.

void TM_LowWtConfig(u16 TM_LowWtThre, u32 NewState)

Configure low-temp warning threshold for comparison with TEMP_OUT.

Parameters:

TM_LowWtThre – When TEMP_OUT <= TM_LowWtThre, the ISR_TM_LOW interrupt flag is set.
NewState – New state of the thermal low-temp warning comparison. This parameter can be ENABLE or DISABLE.

void TM_MaxTempClr(void): Clear the max temperature recorded by thermal.

void TM_MinTempClr(void): Clear the min temperature recorded by thermal.

int TM_PollDataValid(void)

Confirm whether thermal data is valid.

Returns:

Thermal data valid status:

RTK_SUCCESS: thermal data is valid
RTK_FAIL: thermal data is invalid

void TM_PwrProgCmd(u32 NewState)

Enable or disable the specified thermal fields to be programmed.

Parameters:

NewState –
ENABLE or DISABLE.
- ENABLE: Fill TM_PWR field with right password 0x69.
- DISABLE: Fill TM_PWR field with wrong password 0x0.

void TM_StructInit(TM_InitTypeDef *TM_InitStruct)

Initialize the parameters in the TM_InitStruct with default values.

Parameters:

TM_InitStruct – Pointer to a TM_InitTypeDef structure that contains the configuration information for the thermal peripheral.