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 BatMonSupportLPF3.h 34 * 35 * @brief BatMon Support layer 36 * 37 * @anchor ti_drivers_batterymonitor_BatMonSupportLPF3_Overview 38 * # Overview # 39 * The purpose of the BatMon Support layer is to provide a way for multiple 40 * drivers to share the the BATMON hardware resource. The BATMON provides both 41 * temperature and supply voltage measurements. For this reason, both the 42 * Temperature driver and the Battery Monitor driver depends on the BATMON 43 * module. 44 * 45 * Only a combined interrupt request for BATMON exists, and this needs to be 46 * shared by multiple drivers. 47 * 48 * The two main services provided are: 49 * - Initializing the BATMON module 50 * - Dispatching the combined BATMON interrupt (AON_PMU_COMB) to registered 51 * callback functions 52 * 53 * @note The BatMon Support layer is not intended to be used by the application. 54 * It is only intended to be used by TI drivers. 55 * 56 * @anchor ti_drivers_batterymonitor_BatMonSupportLPF3_Usage 57 * # Usage # 58 * 59 * ## Initialisation # 60 * The BatMon Support layer needs to be initialized by calling 61 * #BatMonSupportLPF3_init(). 62 * #BatMonSupportLPF3_init() should be called once before using other BatMon 63 * Support APIs. Subsequent #BatMonSupportLPF3_init() calls will have no 64 * effect. 65 * 66 * ## BATMON Event Callbacks # 67 * The main function of the BatMon Support layer is to dispatch the combined 68 * BATMON interrupt to registered callback functions when certain event flags 69 * are set. 70 * 71 * ### Registering Event Callbacks 72 * There are two functions that register an event callback: 73 * - #BatMonSupportLPF3_registerTemperatureCb() 74 * - #BatMonSupportLPF3_registerBatteryCb() 75 * 76 * Only one Temperature Callback and one Battery Callback can be registered, 77 * and registered callbacks cannot be unregistered. 78 * 79 * @anchor ti_drivers_batterymonitor_BatMonSupportLPF3_Synopsis 80 * # Synopsis # 81 * @anchor ti_drivers_batterymonitor_BatMonSupportLPF3_Code 82 * @code 83 * #include <ti/drivers/BatMonSupportLPF3.h> 84 * 85 * BatMonSupportLPF3_init(); 86 * 87 * BatMonSupportLPF3_registerTemperatureCb(PMUD_EVENT_TEMP_BELOW_LL | PMUD_EVENT_TEMP_OVER_UL, myTempCb); 88 * BatMonSupportLPF3_registerBatteryCb(PMUD_EVENT_BATT_BELOW_LL | PMUD_EVENT_BATT_OVER_UL, myBattCb); 89 * @endcode 90 */ 91 #ifndef ti_drivers_batterymonitor_BatMonSupportLPF3__include 92 #define ti_drivers_batterymonitor_BatMonSupportLPF3__include 93 94 #include <stdbool.h> 95 #include <stddef.h> 96 #include <stdint.h> 97 98 #include <ti/drivers/utils/List.h> 99 100 #ifdef __cplusplus 101 extern "C" { 102 #endif 103 104 /*! 105 * @brief BatMon Support Configuration 106 * 107 * A sample structure is shown below: 108 * @code 109 * const BatMonSupportLPF3_Config BatMonSupportLPF3_config = { 110 * .intNum = INT_CPUIRQ2, 111 * .intPriority = (~0), 112 * .intMux = EVTSVT_CPUIRQ2SEL_PUBID_AON_PMU_COMB, 113 * }; 114 * @endcode 115 */ 116 typedef struct 117 { 118 uint32_t intNum; /*!< Device-specific interrupt number */ 119 uint32_t intPriority; /*!< Device-specific interrupt priority */ 120 uint32_t intMux; /*!< Device-specific interrupt muxing */ 121 } BatMonSupportLPF3_Config; 122 123 /*! 124 * @brief Function prototype for an event callback. 125 * 126 * The callback function is responsible for clearing the event flags associated 127 * with the callback 128 * 129 * @param [in] eventFlags The event flags read from PMUD.EVENT masked with 130 * the event mask used when registering the 131 * callback function in 132 * #BatMonSupportLPF3_registerTemperatureCb() 133 * or #BatMonSupportLPF3_registerBatteryCb(). 134 */ 135 typedef void (*BatMonSupportLPF3_EventCb)(uint32_t eventFlags); 136 137 /*! 138 * @brief This function initializes the BatMon Support layer. 139 * 140 * This function initializes the internal state of the BatMon Support layer. 141 * It must be called before calling any other BatMon Support functions. 142 * Subsequent calls to this function have no effect. 143 */ 144 extern void BatMonSupportLPF3_init(void); 145 146 /*! 147 * @brief This function registers a callback dedicated for the Temperature driver 148 * 149 * @note This function does not set PMUD.EVENTMASK. The @c eventMask parameter 150 * is only used as a filter for when to to call the callback function defined 151 * by @c callback. The calling function is responsible to setting up BATMON to 152 * actually generate the desired events. 153 * 154 * @param [in] eventMask Event mask used as filter for when to call the 155 * callback function defined by @c callback. 156 * In the AON_PMU_COMB ISR the value of PMUD.EVENT 157 * will be AND'ed with @c eventMask, if the result 158 * is non-zero the callback function will be 159 * called. 160 * 161 * @param [in] callback The callback function that is called by the 162 * AON_PMU_COMB ISR if any of the event flags 163 * defined by @c eventMask is set in PMUD.EVENT. 164 */ 165 extern void BatMonSupportLPF3_registerTemperatureCb(uint32_t eventMask, BatMonSupportLPF3_EventCb callback); 166 167 /*! 168 * @brief This function registers a callback dedicated for the Battery Monitor 169 * driver 170 * 171 * @note This function does not set PMUD.EVENTMASK. The @c eventMask parameter 172 * is only used as a filter for when to to call the callback function defined 173 * by @c callback. The calling function is responsible to setting up BATMON to 174 * actually generate the desired events. 175 * 176 * @param [in] eventMask Event mask used as filter for when to call the 177 * callback function defined by @c callback. 178 * In the AON_PMU_COMB ISR the value of PMUD.EVENT 179 * will be AND'ed with @c eventMask, if the result 180 * is non-zero the callback function will be 181 * called. 182 * 183 * @param [in] callback The callback function that is called by the 184 * AON_PMU_COMB ISR if any of the event flags 185 * defined by @c eventMask is set in PMUD.EVENT. 186 */ 187 extern void BatMonSupportLPF3_registerBatteryCb(uint32_t eventMask, BatMonSupportLPF3_EventCb callback); 188 189 #ifdef __cplusplus 190 } 191 #endif 192 193 #endif /* ti_drivers_batterymonitor_BatMonSupportLPF3__include */ 194
