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