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
nrfx_power_usbstatus_get(void)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