1 /*
2  * Copyright (c) 2022-2023, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * *  Redistributions of source code must retain the above copyright
10  *    notice, this list of conditions and the following disclaimer.
11  *
12  * *  Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * *  Neither the name of Texas Instruments Incorporated nor the names of
17  *    its contributors may be used to endorse or promote products derived
18  *    from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /** ============================================================================
33  *  @file       TemperatureLPF3.h
34  *
35  *  @brief      Temperature driver implementation for the Low Power F3 family
36  *
37  *  The temperature driver on Low Power F3 devices is a part of the battery
38  *  monitoring system in AON (always on). It periodically takes measurements of
39  *  the temperature of the chip and will issue interrupts if the configured
40  *  upper limit or lower limit is crossed.
41  *
42  *  # Standby Power Mode Behavior #
43  *  The temperature measurement is active while in standby power mode as well.
44  *  The interrupt used by the temperature module is capable of bringing the
45  *  device out of standby and into active mode to handle it. That means that an
46  *  application will not miss a change in temperature just because the device
47  *  has transitioned to standby power mode. While in standby, the temperature
48  *  will only be sampled during a VDDR recharge pulse. This means that the
49  *  sampling frequency in standby will be determined by the temperature as
50  *  leakage increases with temperature and requires more frequent recharging of
51  *  VDDR.
52  */
53 
54 #ifndef ti_drivers_temperature_TemperatureLPF3__include
55 #define ti_drivers_temperature_TemperatureLPF3__include
56 
57 #include <stdint.h>
58 #include <stdbool.h>
59 
60 #include <ti/drivers/Temperature.h>
61 
62 #ifdef __cplusplus
63 extern "C" {
64 #endif
65 
66 /*!
67  *  @brief Temperature driver configuration struct for Low Power F3 devices
68  *
69  *  This struct globally controls configuration settings for the Temperature
70  *  driver.
71  *
72  *  The Low Power F3 Temperature driver implementation links against a structure
73  *  of this type named TemperatureLPF3_config.
74  *
75  *  This structure must be allocated and configured by the application. If
76  *  SysConfig is used, this struct will be automatically created when the
77  *  Temperature module is used in SysConfig.
78  */
79 typedef struct
80 {
81     /*! @brief  Temperature sensor's interrupt priority.
82      *
83      *  The interrupt line is shared between the temperature sensor and the
84      *  battery voltage monitor on Low Power F3 devices
85      *
86      *  The Low Power F3 devices use either three or two priority bits,
87      *  depending on the device. That means ~0 has the same effect as (7 << 5)
88      *  or (3 << 6), respectively.
89      *
90      *  Setting the priority to 0 is not supported by this driver.
91      *
92      *  HWI's with priority 0 ignore the HWI dispatcher to support zero-latency
93      *  interrupts, thus invalidating the critical sections in this driver.
94      */
95     uint8_t intPriority;
96 } TemperatureLPF3_Config;
97 
98 /**
99  * @brief Enable thermal shutdown monitoring
100  *
101  * Set threshold for thermal shutdown, in degrees Celsius, and enable thermal shutdown monitoring. Once the
102  * temperature of the device reaches or goes above @c shutdownThreshold, the driver will invoke
103  * an internal callback-function that will invoke @ref TemperatureLPF3_triggerThermalShutdown. If a custom shutdown
104  * procedure is required, one would need to install their own callback using @ref Temperature_registerNotifyHigh,
105  * and optionally call @ref TemperatureLPF3_triggerThermalShutdown as the last thing in the custom callback.
106  *
107  * @param shutdownThreshold Thermal shutdown threshold in degrees Celsius
108  */
109 void TemperatureLPF3_enableTSDMonitoring(int16_t shutdownThreshold);
110 
111 /**
112  * @brief Disable thermal shutdown monitoring
113  *
114  * Disable thermal shutdown monitoring. To re-enable, @ref TemperatureLPF3_enableTSDMonitoring must be called again
115  * with the desired temperature threshold.
116  */
117 void TemperatureLPF3_disableTSDMonitoring(void);
118 
119 /**
120  * @brief Trigger thermal shutdown
121  *
122  * Immediately trigger thermal shutdown, and enable the thermal shutdown comparator. The device will remain in
123  * reset for as long as the comparator is high (i.e for as long as the temperature is above 95 degrees C.
124  * See technical reference manual for more details. This function is called if TSD monitoring is enabled through
125  * @ref TemperatureLPF3_enableTSDMonitoring and the given threshold temperature is reached. The threshold should
126  * always be set to greater than 95, or the device will immediately come back out of reset. Typically, the threshold
127  * would be set near the maximum operating temperature of 125 degrees C.
128  *
129  * @note Calling this function will immediately bring the device into reset
130  */
131 void TemperatureLPF3_triggerThermalShutdown(void);
132 
133 #ifdef __cplusplus
134 }
135 #endif
136 
137 #endif /* ti_drivers_temperature_TemperatureLPF3__include */
138