1 /* 2 * Copyright (c) 2017 - 2018, Nordic Semiconductor ASA 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 are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, this 9 * list of conditions and the following disclaimer. 10 * 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * 3. Neither the name of the copyright holder nor the names of its 16 * contributors may be used to endorse or promote products derived from this 17 * software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 23 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29 * POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 #ifndef NRFX_POWER_H__ 33 #define NRFX_POWER_H__ 34 35 #include <nrfx.h> 36 #include <hal/nrf_power.h> 37 #include <nrfx_power_clock.h> 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 /** 44 * @defgroup nrfx_power POWER driver 45 * @{ 46 * @ingroup nrf_power 47 * @brief POWER peripheral driver. 48 */ 49 50 /** 51 * @brief Power mode possible configurations 52 */ 53 typedef enum 54 { 55 NRFX_POWER_MODE_CONSTLAT, /**< Constant latency mode */ 56 NRFX_POWER_MODE_LOWPWR /**< Low power mode */ 57 }nrfx_power_mode_t; 58 59 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__) 60 /** 61 * @brief Events from power system 62 */ 63 typedef enum 64 { 65 NRFX_POWER_SLEEP_EVT_ENTER, /**< CPU entered WFI/WFE sleep 66 * 67 * Keep in mind that if this interrupt is enabled, 68 * it means that CPU was waken up just after WFI by this interrupt. 69 */ 70 NRFX_POWER_SLEEP_EVT_EXIT /**< CPU exited WFI/WFE sleep */ 71 }nrfx_power_sleep_evt_t; 72 #endif /* NRF_POWER_HAS_SLEEPEVT */ 73 74 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__) 75 /** 76 * @brief Events from USB power system 77 */ 78 typedef enum 79 { 80 NRFX_POWER_USB_EVT_DETECTED, /**< USB power detected on the connector (plugged in). */ 81 NRFX_POWER_USB_EVT_REMOVED, /**< USB power removed from the connector. */ 82 NRFX_POWER_USB_EVT_READY /**< USB power regulator ready. */ 83 }nrfx_power_usb_evt_t; 84 85 /** 86 * @brief USB power state 87 * 88 * The single enumerator that holds all data about current state of USB 89 * related POWER. 90 * 91 * Organized this way that higher power state has higher numeric value 92 */ 93 typedef enum 94 { 95 NRFX_POWER_USB_STATE_DISCONNECTED, /**< No power on USB lines detected */ 96 NRFX_POWER_USB_STATE_CONNECTED, /**< The USB power is detected, but USB power regulator is not ready */ 97 NRFX_POWER_USB_STATE_READY /**< From the power point of view USB is ready for working */ 98 }nrfx_power_usb_state_t; 99 #endif /* NRF_POWER_HAS_USBREG */ 100 101 /** 102 * @name Callback types 103 * 104 * Defined types of callback functions 105 * @{ 106 */ 107 /** 108 * @brief Event handler for power failure warning 109 */ 110 typedef void (*nrfx_power_pofwarn_event_handler_t)(void); 111 112 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__) 113 /** 114 * @brief Event handler for entering/exiting sleep 115 * 116 * @param event Event type 117 */ 118 typedef void (*nrfx_power_sleep_event_handler_t)(nrfx_power_sleep_evt_t event); 119 #endif 120 121 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__) 122 /** 123 * @brief Event handler for USB related power events 124 * 125 * @param event Event type 126 */ 127 typedef void (*nrfx_power_usb_event_handler_t)(nrfx_power_usb_evt_t event); 128 #endif 129 /** @} */ 130 131 /** 132 * @brief General power configuration 133 * 134 * Parameters required to initialize power driver. 135 */ 136 typedef struct 137 { 138 /** 139 * @brief Enable main DCDC regulator 140 * 141 * This bit only informs the driver that elements for DCDC regulator 142 * are installed and regulator can be used. 143 * The regulator would be enabled or disabled automatically 144 * by the hardware, basing on current power requirement. 145 */ 146 bool dcdcen:1; 147 148 #if NRF_POWER_HAS_VDDH || defined(__NRFX_DOXYGEN__) 149 /** 150 * @brief Enable HV DCDC regulator 151 * 152 * This bit only informs the driver that elements for DCDC regulator 153 * are installed and regulator can be used. 154 * The regulator would be enabled or disabled automatically 155 * by the hardware, basing on current power requirement. 156 */ 157 bool dcdcenhv: 1; 158 #endif 159 }nrfx_power_config_t; 160 161 /** 162 * @brief The configuration for power failure comparator 163 * 164 * Configuration used to enable and configure power failure comparator 165 */ 166 typedef struct 167 { 168 nrfx_power_pofwarn_event_handler_t handler; //!< Event handler 169 #if NRF_POWER_HAS_POFCON || defined(__NRFX_DOXYGEN__) 170 nrf_power_pof_thr_t thr; //!< Threshold for power failure detection 171 #endif 172 #if NRF_POWER_HAS_VDDH || defined(__NRFX_DOXYGEN__) 173 nrf_power_pof_thrvddh_t thrvddh; //!< Threshold for power failure detection on VDDH pin 174 #endif 175 }nrfx_power_pofwarn_config_t; 176 177 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__) 178 /** 179 * @brief The configuration of sleep event processing 180 * 181 * Configuration used to enable and configure sleep event handling 182 */ 183 typedef struct 184 { 185 nrfx_power_sleep_event_handler_t handler; //!< Event handler 186 bool en_enter:1; //!< Enable event on sleep entering 187 bool en_exit :1; //!< Enable event on sleep exiting 188 }nrfx_power_sleepevt_config_t; 189 #endif 190 191 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__) 192 /** 193 * @brief The configuration of USB related power events 194 * 195 * Configuration used to enable and configure USB power event handling 196 */ 197 typedef struct 198 { 199 nrfx_power_usb_event_handler_t handler; //!< Event processing 200 }nrfx_power_usbevt_config_t; 201 #endif /* NRF_POWER_HAS_USBREG */ 202 203 /** 204 * @brief Function for getting the handler of the power failure comparator. 205 * @return Handler of the power failure comparator. 206 */ 207 nrfx_power_pofwarn_event_handler_t nrfx_power_pof_handler_get(void); 208 209 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__) 210 /** 211 * @brief Function for getting the handler of the USB power. 212 * @return Handler of the USB power. 213 */ 214 nrfx_power_usb_event_handler_t nrfx_power_usb_handler_get(void); 215 #endif 216 217 /** 218 * @brief Initialize power module driver 219 * 220 * Enabled power module driver would process all the interrupts from power system. 221 * 222 * @param[in] p_config Pointer to the structure with initial configuration. 223 * 224 * @retval NRFX_SUCCESS Successfully initialized. 225 * @retval NRFX_ERROR_ALREADY_INITIALIZED Module was already initialized. 226 */ 227 nrfx_err_t nrfx_power_init(nrfx_power_config_t const * p_config); 228 229 /** 230 * @brief Unintialize power module driver 231 * 232 * Disables all the interrupt handling in the module. 233 * 234 * @sa nrfx_power_init 235 */ 236 void nrfx_power_uninit(void); 237 238 #if NRF_POWER_HAS_POFCON || defined(__NRFX_DOXYGEN__) 239 /** 240 * @brief Initialize power failure comparator 241 * 242 * Configures the power failure comparator. This function does not setup and enable it. 243 * Those steps can be done with functions @ref nrfx_power_pof_enable and @ref nrfx_power_pof_disable 244 * or with Softdevice API (when Softdevice is using). 245 * 246 * @param[in] p_config Configuration with values and event handler. 247 * If event handler is set to NULL, interrupt would be disabled. 248 */ 249 void nrfx_power_pof_init(nrfx_power_pofwarn_config_t const * p_config); 250 251 /** 252 * @brief Enable power failure comparator 253 * Sets and enables interrupt of the power failure comparator. This functions cannot be using 254 * when Softdevice is enabled. If event handler set in init function is set to NULL, interrupt 255 * would be disabled. 256 * 257 * @param[in] p_config Configuration with values and event handler. 258 */ 259 void nrfx_power_pof_enable(nrfx_power_pofwarn_config_t const * p_config); 260 261 /** 262 * @brief Disable the power failure comparator 263 * 264 * Disables the power failure comparator interrupt. 265 */ 266 void nrfx_power_pof_disable(void); 267 268 /** 269 * @brief Clear the power failure comparator settings 270 * 271 * Clears the settings of the power failure comparator. 272 */ 273 void nrfx_power_pof_uninit(void); 274 #endif // NRF_POWER_HAS_POFCON || defined(__NRFX_DOXYGEN__) 275 276 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__) 277 /** 278 * @brief Initialize sleep entering and exiting events processing 279 * 280 * Configures and setups the sleep event processing. 281 * 282 * @param[in] p_config Configuration with values and event handler. 283 * 284 * @sa nrfx_power_sleepevt_uninit 285 * 286 */ 287 void nrfx_power_sleepevt_init(nrfx_power_sleepevt_config_t const * p_config); 288 289 /** 290 * @brief Enable sleep entering and exiting events processing 291 * 292 * @param[in] p_config Configuration with values and event handler. 293 */ 294 void nrfx_power_sleepevt_enable(nrfx_power_sleepevt_config_t const * p_config); 295 296 /** 297 * @brief Disable sleep entering and exiting events processing 298 */ 299 void nrfx_power_sleepevt_disable(void); 300 301 /** 302 * @brief Uninitialize sleep entering and exiting events processing 303 * 304 * @sa nrfx_power_sleepevt_init 305 */ 306 void nrfx_power_sleepevt_uninit(void); 307 #endif /* NRF_POWER_HAS_SLEEPEVT */ 308 309 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__) 310 /** 311 * @brief Initialize USB power event processing 312 * 313 * Configures and setups the USB power event processing. 314 * 315 * @param[in] p_config Configuration with values and event handler. 316 * 317 * @sa nrfx_power_usbevt_uninit 318 */ 319 void nrfx_power_usbevt_init(nrfx_power_usbevt_config_t const * p_config); 320 321 /** 322 * @brief Enable USB power event processing 323 */ 324 void nrfx_power_usbevt_enable(void); 325 326 /** 327 * @brief Disable USB power event processing 328 */ 329 void nrfx_power_usbevt_disable(void); 330 331 /** 332 * @brief Uninitalize USB power event processing 333 * 334 * @sa nrfx_power_usbevt_init 335 */ 336 void nrfx_power_usbevt_uninit(void); 337 338 /** 339 * @brief Get the status of USB power 340 * 341 * @return Current USB power status 342 */ 343 __STATIC_INLINE nrfx_power_usb_state_t nrfx_power_usbstatus_get(void); 344 345 #endif /* NRF_POWER_HAS_USBREG */ 346 347 #ifndef SUPPRESS_INLINE_IMPLEMENTATION 348 349 #if NRF_POWER_HAS_USBREG 350 __STATIC_INLINE nrfx_power_usb_state_t nrfx_power_usbstatus_get(void) 351 { 352 uint32_t status = nrf_power_usbregstatus_get(); 353 if(0 == (status & NRF_POWER_USBREGSTATUS_VBUSDETECT_MASK)) 354 { 355 return NRFX_POWER_USB_STATE_DISCONNECTED; 356 } 357 if(0 == (status & NRF_POWER_USBREGSTATUS_OUTPUTRDY_MASK)) 358 { 359 return NRFX_POWER_USB_STATE_CONNECTED; 360 } 361 return NRFX_POWER_USB_STATE_READY; 362 } 363 #endif /* NRF_POWER_HAS_USBREG */ 364 365 #endif /* SUPPRESS_INLINE_IMPLEMENTATION */ 366 367 368 void nrfx_power_irq_handler(void); 369 370 371 /** @} */ 372 373 #ifdef __cplusplus 374 } 375 #endif 376 377 #endif /* NRFX_POWER_H__ */ 378