1 /*
2  * Copyright (c) 2017 - 2020, 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 #include "nrfx_power_compat.h"
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 /**
45  * @defgroup nrfx_power POWER driver
46  * @{
47  * @ingroup nrf_power
48  * @brief   POWER peripheral driver.
49  */
50 
51 #if NRF_POWER_HAS_POFCON || NRFX_CHECK(NRF_REGULATORS_HAS_POFCON) || defined(__NRFX_DOXYGEN__)
52 /** @brief Symbol indicating whether the power failure comparator is supported. */
53 #define NRFX_POWER_SUPPORTS_POFCON 1
54 #else
55 #define NRFX_POWER_SUPPORTS_POFCON 0
56 #endif
57 
58 #if NRF_POWER_HAS_POFCON_VDDH || NRFX_CHECK(NRF_REGULATORS_HAS_POFCON_VDDH) || \
59     defined(__NRFX_DOXYGEN__)
60 /** @brief Symbol indicating whether the power failure comparator for VDDH is supported. */
61 #define NRFX_POWER_SUPPORTS_POFCON_VDDH 1
62 #else
63 #define NRFX_POWER_SUPPORTS_POFCON_VDDH 0
64 #endif
65 
66 #if NRF_POWER_HAS_DCDCEN_VDDH || NRFX_CHECK(NRF_REGULATORS_HAS_DCDCEN_VDDH) || \
67     defined(__NRFX_DOXYGEN__)
68 /** @brief Symbol indicating whether the VDDH regulator is supported. */
69 #define NRFX_POWER_SUPPORTS_DCDCEN_VDDH 1
70 #else
71 #define NRFX_POWER_SUPPORTS_DCDCEN_VDDH 0
72 #endif
73 
74 /**
75  * @brief Power mode possible configurations
76  */
77 typedef enum
78 {
79     NRFX_POWER_MODE_CONSTLAT, /**< Constant latency mode */
80     NRFX_POWER_MODE_LOWPWR    /**< Low power mode        */
81 }nrfx_power_mode_t;
82 
83 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__)
84 /**
85  * @brief Events from power system
86  */
87 typedef enum
88 {
89     NRFX_POWER_SLEEP_EVT_ENTER, /**< CPU entered WFI/WFE sleep
90                                  *
91                                  * Keep in mind that if this interrupt is enabled,
92                                  * it means that CPU was waken up just after WFI by this interrupt.
93                                  */
94     NRFX_POWER_SLEEP_EVT_EXIT   /**< CPU exited WFI/WFE sleep */
95 }nrfx_power_sleep_evt_t;
96 #endif /* NRF_POWER_HAS_SLEEPEVT */
97 
98 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
99 /**
100  * @brief Events from USB power system
101  */
102 typedef enum
103 {
104     NRFX_POWER_USB_EVT_DETECTED, /**< USB power detected on the connector (plugged in). */
105     NRFX_POWER_USB_EVT_REMOVED,  /**< USB power removed from the connector. */
106     NRFX_POWER_USB_EVT_READY     /**< USB power regulator ready. */
107 }nrfx_power_usb_evt_t;
108 
109 /**
110  * @brief USB power state
111  *
112  * The single enumerator that holds all data about current state of USB
113  * related POWER.
114  *
115  * Organized this way that higher power state has higher numeric value
116  */
117 typedef enum
118 {
119     NRFX_POWER_USB_STATE_DISCONNECTED, /**< No power on USB lines detected. */
120     NRFX_POWER_USB_STATE_CONNECTED,    /**< The USB power is detected, but USB power regulator is not ready. */
121     NRFX_POWER_USB_STATE_READY         /**< From the power viewpoint, USB is ready for working. */
122 }nrfx_power_usb_state_t;
123 #endif // NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
124 
125 /**
126  * @name Callback types
127  *
128  * Defined types of callback functions.
129  * @{
130  */
131 /**
132  * @brief Event handler for power failure warning.
133  */
134 typedef void (*nrfx_power_pofwarn_event_handler_t)(void);
135 
136 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__)
137 /**
138  * @brief Event handler for the sleep events.
139  *
140  * @param event Event type
141  */
142 typedef void (*nrfx_power_sleep_event_handler_t)(nrfx_power_sleep_evt_t event);
143 #endif
144 
145 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
146 /**
147  * @brief Event handler for the USB-related power events.
148  *
149  * @param event Event type
150  */
151 typedef void (*nrfx_power_usb_event_handler_t)(nrfx_power_usb_evt_t event);
152 #endif
153 /** @} */
154 
155 /**
156  * @brief General power configuration
157  *
158  * Parameters required to initialize power driver.
159  */
160 typedef struct
161 {
162     /**
163      * @brief Enable main DCDC regulator.
164      *
165      * This bit only informs the driver that elements for DCDC regulator
166      * are installed and the regulator can be used.
167      * The regulator will be enabled or disabled automatically
168      * by the hardware, basing on current power requirement.
169      */
170     bool dcdcen:1;
171 
172 #if NRFX_POWER_SUPPORTS_DCDCEN_VDDH
173     /**
174      * @brief Enable HV DCDC regulator.
175      *
176      * This bit only informs the driver that elements for DCDC regulator
177      * are installed and the regulator can be used.
178      * The regulator will be enabled or disabled automatically
179      * by the hardware, basing on current power requirement.
180      */
181     bool dcdcenhv: 1;
182 #endif
183 }nrfx_power_config_t;
184 
185 /**
186  * @brief The configuration for power failure comparator.
187  *
188  * Configuration used to enable and configure the power failure comparator.
189  */
190 typedef struct
191 {
192     nrfx_power_pofwarn_event_handler_t handler; //!< Event handler.
193 #if NRFX_POWER_SUPPORTS_POFCON
194     nrf_power_pof_thr_t                thr;     //!< Threshold for power failure detection
195 #endif
196 #if NRFX_POWER_SUPPORTS_POFCON_VDDH
197     nrf_power_pof_thrvddh_t            thrvddh; //!< Threshold for power failure detection on the VDDH pin.
198 #endif
199 }nrfx_power_pofwarn_config_t;
200 
201 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__)
202 /**
203  * @brief The configuration of sleep event processing.
204  *
205  * Configuration used to enable and configure sleep event handling.
206  */
207 typedef struct
208 {
209     nrfx_power_sleep_event_handler_t handler;    //!< Event handler.
210     bool                             en_enter:1; //!< Enable event on sleep entering.
211     bool                             en_exit :1; //!< Enable event on sleep exiting.
212 }nrfx_power_sleepevt_config_t;
213 #endif
214 
215 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
216 /**
217  * @brief The configuration of the USB-related power events.
218  *
219  * Configuration used to enable and configure USB power event handling.
220  */
221 typedef struct
222 {
223     nrfx_power_usb_event_handler_t handler; //!< Event processing.
224 }nrfx_power_usbevt_config_t;
225 #endif // NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
226 
227 /**
228  * @brief Function for getting the handler of the power failure comparator.
229  * @return Handler of the power failure comparator.
230  */
231 nrfx_power_pofwarn_event_handler_t nrfx_power_pof_handler_get(void);
232 
233 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
234 /**
235  * @brief Function for getting the handler of the USB power.
236  * @return Handler of the USB power.
237  */
238 nrfx_power_usb_event_handler_t nrfx_power_usb_handler_get(void);
239 #endif // NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
240 
241 /**
242  * @brief Function for initializing the power module driver.
243  *
244  * Enabled power module driver processes all the interrupts from the power system.
245  *
246  * @param[in] p_config Pointer to the structure with the initial configuration.
247  *
248  * @retval NRFX_SUCCESS                   Successfully initialized.
249  * @retval NRFX_ERROR_ALREADY_INITIALIZED Module was already initialized.
250  */
251 nrfx_err_t nrfx_power_init(nrfx_power_config_t const * p_config);
252 
253 /**
254  * @brief Function for unintializing the power module driver.
255  *
256  * Disables all the interrupt handling in the module.
257  *
258  * @sa nrfx_power_init
259  */
260 void nrfx_power_uninit(void);
261 
262 #if NRFX_POWER_SUPPORTS_POFCON
263 /**
264  * @brief Function for initializing the power failure comparator.
265  *
266  * Configures the power failure comparator. This function does not set it up and enable it.
267  * These steps can be done with functions @ref nrfx_power_pof_enable and @ref nrfx_power_pof_disable
268  * or with the SoftDevice API (when in use).
269  *
270  * @param[in] p_config Configuration with values and event handler.
271  *                     If event handler is set to NULL, the interrupt will be disabled.
272  */
273 void nrfx_power_pof_init(nrfx_power_pofwarn_config_t const * p_config);
274 
275 /**
276  * @brief Function for enabling the power failure comparator.
277  * Sets and enables the interrupt of the power failure comparator. This function cannot be in use
278  * when SoftDevice is enabled. If the event handler set in the init function is set to NULL, the interrupt
279  * will be disabled.
280  *
281  * @param[in] p_config Configuration with values and event handler.
282  */
283 void nrfx_power_pof_enable(nrfx_power_pofwarn_config_t const * p_config);
284 
285 /**
286  * @brief Function for disabling the power failure comparator.
287  *
288  * Disables the power failure comparator interrupt.
289  */
290 void nrfx_power_pof_disable(void);
291 
292 /**
293  * @brief Function for clearing the power failure comparator settings.
294  *
295  * Clears the settings of the power failure comparator.
296  */
297 void nrfx_power_pof_uninit(void);
298 #endif // NRFX_POWER_SUPPORTS_POFCON
299 
300 #if NRF_POWER_HAS_SLEEPEVT || defined(__NRFX_DOXYGEN__)
301 /**
302  * @brief Function for initializing the processing of the sleep events.
303  *
304  * Configures and sets up the sleep event processing.
305  *
306  * @param[in] p_config Configuration with values and event handler.
307  *
308  * @sa nrfx_power_sleepevt_uninit
309  *
310  */
311 void nrfx_power_sleepevt_init(nrfx_power_sleepevt_config_t const * p_config);
312 
313 /**
314  * @brief Function for enabling the processing of the sleep events.
315  *
316  * @param[in] p_config Configuration with values and event handler.
317  */
318 void nrfx_power_sleepevt_enable(nrfx_power_sleepevt_config_t const * p_config);
319 
320 /** @brief Function for disabling the processing of the sleep events. */
321 void nrfx_power_sleepevt_disable(void);
322 
323 /**
324  * @brief Function for uninitializing the processing of the sleep events.
325  *
326  * @sa nrfx_power_sleepevt_init
327  */
328 void nrfx_power_sleepevt_uninit(void);
329 #endif /* NRF_POWER_HAS_SLEEPEVT */
330 
331 #if NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
332 /**
333  * @brief Function for initializing the processing of USB power event.
334  *
335  * Configures and sets up the USB power event processing.
336  *
337  * @param[in] p_config Configuration with values and event handler.
338  *
339  * @sa nrfx_power_usbevt_uninit
340  */
341 void nrfx_power_usbevt_init(nrfx_power_usbevt_config_t const * p_config);
342 
343 /** @brief Function for enabling the processing of USB power event. */
344 void nrfx_power_usbevt_enable(void);
345 
346 /** @brief Function for disabling the processing of USB power event. */
347 void nrfx_power_usbevt_disable(void);
348 
349 /**
350  * @brief Function for uninitalizing the processing of USB power event.
351  *
352  * @sa nrfx_power_usbevt_init
353  */
354 void nrfx_power_usbevt_uninit(void);
355 
356 /**
357  * @brief Function for getting the status of USB power.
358  *
359  * @return Current USB power status.
360  */
361 NRFX_STATIC_INLINE nrfx_power_usb_state_t nrfx_power_usbstatus_get(void);
362 
363 #endif // NRF_POWER_HAS_USBREG || defined(__NRFX_DOXYGEN__)
364 
365 #ifndef NRFX_DECLARE_ONLY
366 #if NRF_POWER_HAS_USBREG
nrfx_power_usbstatus_get(void)367 NRFX_STATIC_INLINE nrfx_power_usb_state_t nrfx_power_usbstatus_get(void)
368 {
369     uint32_t status = nrf_power_usbregstatus_get(NRF_POWER);
370     if(0 == (status & NRF_POWER_USBREGSTATUS_VBUSDETECT_MASK))
371     {
372         return NRFX_POWER_USB_STATE_DISCONNECTED;
373     }
374     if(0 == (status & NRF_POWER_USBREGSTATUS_OUTPUTRDY_MASK))
375     {
376         return NRFX_POWER_USB_STATE_CONNECTED;
377     }
378     return NRFX_POWER_USB_STATE_READY;
379 }
380 #endif // NRF_POWER_HAS_USBREG
381 #endif // NRFX_DECLARE_ONLY
382 
383 /** @} */
384 
385 
386 void nrfx_power_irq_handler(void);
387 
388 
389 #ifdef __cplusplus
390 }
391 #endif
392 
393 #endif /* NRFX_POWER_H__ */
394