1 /*
2 * Copyright (c) 2015 - 2025, 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_COMP_H__
35 #define NRFX_COMP_H__
36
37 #include <nrfx.h>
38 #include <haly/nrfy_comp.h>
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
44 /**
45 * @defgroup nrfx_comp COMP driver
46 * @{
47 * @ingroup nrf_comp
48 * @brief Comparator (COMP) peripheral driver.
49 */
50
51 /**
52 * @brief Macro for converting the threshold voltage to an integer value
53 * (needed by the COMP_TH register).
54 *
55 * @param[in] vol Voltage to be changed to COMP_TH register value. This value
56 * must not be smaller than reference voltage divided by 64.
57 * @param[in] ref Reference voltage.
58 */
59 #define NRFX_COMP_VOLTAGE_THRESHOLD_TO_INT(vol, ref) \
60 (uint8_t)(((vol) > ((ref) / 64)) ? (NRFX_ROUNDED_DIV((vol) * 64,(ref)) - 1) : 0)
61
62 /**
63 * @brief COMP event handler function type.
64 *
65 * @param[in] event COMP event.
66 */
67 typedef void (* nrfx_comp_event_handler_t)(nrf_comp_event_t event);
68
69 /**
70 * @brief COMP shortcut masks.
71 *
72 * @deprecated Use @ref nrf_comp_short_mask_t instead.
73 */
74 typedef enum
75 {
76 NRFX_COMP_SHORT_STOP_AFTER_CROSS_EVT = NRF_COMP_SHORT_STOP_CROSS_MASK, ///< Shortcut between the CROSS event and the STOP task.
77 NRFX_COMP_SHORT_STOP_AFTER_UP_EVT = NRF_COMP_SHORT_STOP_UP_MASK, ///< Shortcut between the UP event and the STOP task.
78 NRFX_COMP_SHORT_STOP_AFTER_DOWN_EVT = NRF_COMP_SHORT_STOP_DOWN_MASK ///< Shortcut between the DOWN event and the STOP task.
79 } nrfx_comp_short_mask_t;
80
81 /**
82 * @brief COMP events masks.
83 *
84 * @deprecated Use @ref nrf_comp_int_mask_t instead.
85 */
86 typedef enum
87 {
88 NRFX_COMP_EVT_EN_CROSS_MASK = NRF_COMP_INT_CROSS_MASK, ///< CROSS event (generated after VIN+ == VIN-).
89 NRFX_COMP_EVT_EN_UP_MASK = NRF_COMP_INT_UP_MASK, ///< UP event (generated when VIN+ crosses VIN- while increasing).
90 NRFX_COMP_EVT_EN_DOWN_MASK = NRF_COMP_INT_DOWN_MASK, ///< DOWN event (generated when VIN+ crosses VIN- while decreasing).
91 NRFX_COMP_EVT_EN_READY_MASK = NRF_COMP_INT_READY_MASK ///< READY event (generated when the module is ready).
92 } nrfx_comp_evt_en_mask_t;
93
94 /** @brief COMP configuration. */
95 typedef struct
96 {
97 nrf_comp_ref_t reference; ///< Reference selection.
98 nrf_comp_ext_ref_t ext_ref; ///< External analog reference selection.
99 nrf_comp_main_mode_t main_mode; ///< Main operation mode.
100 nrf_comp_th_t threshold; ///< Structure holding THDOWN and THUP values needed by the COMP_TH register.
101 nrf_comp_sp_mode_t speed_mode; ///< Speed and power mode.
102 nrf_comp_hyst_t hyst; ///< Comparator hysteresis.
103 #if NRF_COMP_HAS_ISOURCE
104 nrf_isource_t isource; ///< Current source selected on analog input.
105 #endif
106 nrf_comp_input_t input; ///< Input to be monitored.
107 uint8_t interrupt_priority; ///< Interrupt priority.
108 } nrfx_comp_config_t;
109
110 /** @brief COMP threshold default configuration. */
111 #define NRFX_COMP_CONFIG_TH \
112 { \
113 .th_down = NRFX_COMP_VOLTAGE_THRESHOLD_TO_INT(0.5, 1.2), \
114 .th_up = NRFX_COMP_VOLTAGE_THRESHOLD_TO_INT(1.0, 1.2) \
115 }
116
117 /**
118 * @brief COMP driver default configuration.
119 *
120 * This configuration sets up COMP with the following options:
121 * - single-ended mode
122 * - reference voltage: internal 1.2 V
123 * - lower threshold: 0.5 V
124 * - upper threshold: 1.0 V
125 * - high speed mode
126 * - hysteresis disabled
127 * - current source disabled
128 *
129 * @param[in] _input Analog input.
130 */
131 #define NRFX_COMP_DEFAULT_CONFIG(_input) \
132 { \
133 .reference = NRF_COMP_REF_INT_1V2, \
134 .main_mode = NRF_COMP_MAIN_MODE_SE, \
135 .threshold = NRFX_COMP_CONFIG_TH, \
136 .speed_mode = NRF_COMP_SP_MODE_HIGH, \
137 .hyst = NRF_COMP_HYST_NO_HYST, \
138 NRFX_COND_CODE_1(NRF_COMP_HAS_ISOURCE, (.isource = NRF_COMP_ISOURCE_OFF,), ()) \
139 .input = (nrf_comp_input_t)_input, \
140 .interrupt_priority = NRFX_COMP_DEFAULT_CONFIG_IRQ_PRIORITY \
141 }
142
143 /**
144 * @brief Function for initializing the COMP driver.
145 *
146 * This function initializes the COMP driver, but does not enable the peripheral or any interrupts.
147 * To start the driver, call the function @ref nrfx_comp_start() after initialization.
148 *
149 * @param[in] p_config Pointer to the structure with the initial configuration.
150 * @param[in] event_handler Event handler provided by the user.
151 * Must not be NULL.
152 *
153 * @retval NRFX_SUCCESS Initialization was successful.
154 * @retval NRFX_ERROR_ALREADY The driver is already initialized.
155 * @retval NRFX_ERROR_INVALID_STATE The driver is already initialized.
156 * Deprecated - use @ref NRFX_ERROR_ALREADY instead.
157 * @retval NRFX_ERROR_BUSY The LPCOMP peripheral is already in use.
158 * This is possible only if @ref nrfx_prs module
159 * is enabled.
160 */
161 nrfx_err_t nrfx_comp_init(nrfx_comp_config_t const * p_config,
162 nrfx_comp_event_handler_t event_handler);
163
164 /**
165 * @brief Function for reconfiguring the COMP driver.
166 *
167 * @param[in] p_config Pointer to the structure with the configuration.
168 *
169 * @retval NRFX_SUCCESS Reconfiguration was successful.
170 * @retval NRFX_ERROR_BUSY The driver is running and cannot be reconfigured.
171 * @retval NRFX_ERROR_INVALID_STATE The driver is uninitialized.
172 */
173 nrfx_err_t nrfx_comp_reconfigure(nrfx_comp_config_t const * p_config);
174
175 /**
176 * @brief Function for uninitializing the COMP driver.
177 *
178 * This function uninitializes the COMP driver. The COMP peripheral and
179 * its interrupts are disabled, and local variables are cleaned. After this call, you must
180 * initialize the driver again by calling nrfx_comp_init() if you want to use it.
181 *
182 * @sa nrfx_comp_stop
183 */
184 void nrfx_comp_uninit(void);
185
186 /**
187 * @brief Function for checking if the COMP driver is initialized.
188 *
189 * @retval true Driver is already initialized.
190 * @retval false Driver is not initialized.
191 */
192 bool nrfx_comp_init_check(void);
193
194 /**
195 * @brief Function for setting the analog input.
196 *
197 * @param[in] psel COMP analog pin selection.
198 */
199 void nrfx_comp_pin_select(nrf_comp_input_t psel);
200
201 /**
202 * @brief Function for starting the COMP peripheral and interrupts.
203 *
204 * Before calling this function, the driver must be initialized. This function
205 * enables the COMP peripheral and its interrupts.
206 *
207 * @param[in] comp_evt_en_mask Mask of events to be enabled. This parameter is to be built as
208 * an OR of elements from @ref nrf_comp_int_mask_t.
209 * @param[in] comp_shorts_mask Mask of shortcuts to be enabled. This parameter is to be built as
210 * an OR of elements from @ref nrf_comp_short_mask_t.
211 *
212 * @sa nrfx_comp_init
213 */
214 void nrfx_comp_start(uint32_t comp_evt_en_mask, uint32_t comp_shorts_mask);
215
216 /**
217 * @brief Function for stopping the COMP peripheral.
218 *
219 * Before calling this function, the driver must be enabled. This function disables the COMP
220 * peripheral and its interrupts.
221 *
222 * @sa nrfx_comp_uninit
223 */
224 void nrfx_comp_stop(void);
225
226 /**
227 * @brief Function for copying the current state of the comparator result to the RESULT register.
228 *
229 * @retval 0 The input voltage is below the threshold (VIN+ < VIN-).
230 * @retval 1 The input voltage is above the threshold (VIN+ > VIN-).
231 */
232 uint32_t nrfx_comp_sample(void);
233
234 /**
235 * @brief Function for getting the address of a COMP task.
236 *
237 * @param[in] task COMP task.
238 *
239 * @return Address of the given COMP task.
240 */
241 NRFX_STATIC_INLINE uint32_t nrfx_comp_task_address_get(nrf_comp_task_t task);
242
243 /**
244 * @brief Function for getting the address of a COMP event.
245 *
246 * @param[in] event COMP event.
247 *
248 * @return Address of the given COMP event.
249 */
250 NRFX_STATIC_INLINE uint32_t nrfx_comp_event_address_get(nrf_comp_event_t event);
251
252 #ifndef NRFX_DECLARE_ONLY
nrfx_comp_task_address_get(nrf_comp_task_t task)253 NRFX_STATIC_INLINE uint32_t nrfx_comp_task_address_get(nrf_comp_task_t task)
254 {
255 return nrfy_comp_task_address_get(NRF_COMP, task);
256 }
257
nrfx_comp_event_address_get(nrf_comp_event_t event)258 NRFX_STATIC_INLINE uint32_t nrfx_comp_event_address_get(nrf_comp_event_t event)
259 {
260 return nrfy_comp_event_address_get(NRF_COMP, event);
261 }
262 #endif // NRFX_DECLARE_ONLY
263
264 /** @} */
265
266
267 void nrfx_comp_irq_handler(void);
268
269
270 #ifdef __cplusplus
271 }
272 #endif
273
274 #endif // NRFX_COMP_H__
275
