1 /*
2 * Copyright 2017-2020 NXP
3 * All rights reserved.
4 *
5 * SPDX-License-Identifier: BSD-3-Clause
6 */
7 #ifndef __FSL_CAPT_H__
8 #define __FSL_CAPT_H__
9
10 #include "fsl_common.h"
11
12 /*! @addtogroup capt */
13 /*! @{*/
14
15 /*! @file */
16
17 /*******************************************************************************
18 * Definitions
19 ******************************************************************************/
20
21 /*! @name Driver version */
22 /*@{*/
23 /*! @brief CAPT driver version. */
24 #define FSL_CAPT_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))
25 /*@}*/
26
27 #define CAPT_GET_XMAX_NUMBER(mask) (((CAPT_STATUS_XMAX_MASK & (mask)) >> CAPT_STATUS_XMAX_SHIFT) + 1)
28
29 /*!
30 * @brief The enumeration for X pins.
31 */
32 enum _capt_xpins
33 {
34 kCAPT_X0Pin = 1U << 0U, /*!< CAPT_X0 pin. */
35 kCAPT_X1Pin = 1U << 1U, /*!< CAPT_X1 pin. */
36 kCAPT_X2Pin = 1U << 2U, /*!< CAPT_X2 pin. */
37 kCAPT_X3Pin = 1U << 3U, /*!< CAPT_X3 pin. */
38 kCAPT_X4Pin = 1U << 4U, /*!< CAPT_X4 pin. */
39 kCAPT_X5Pin = 1U << 5U, /*!< CAPT_X5 pin. */
40 kCAPT_X6Pin = 1U << 6U, /*!< CAPT_X6 pin. */
41 kCAPT_X7Pin = 1U << 7U, /*!< CAPT_X7 pin. */
42 kCAPT_X8Pin = 1U << 8U, /*!< CAPT_X8 pin. */
43 kCAPT_X9Pin = 1U << 9U, /*!< CAPT_X9 pin. */
44 kCAPT_X10Pin = 1U << 10U, /*!< CAPT_X10 pin. */
45 kCAPT_X11Pin = 1U << 11U, /*!< CAPT_X11 pin. */
46 kCAPT_X12Pin = 1U << 12U, /*!< CAPT_X12 pin. */
47 kCAPT_X13Pin = 1U << 13U, /*!< CAPT_X13 pin. */
48 kCAPT_X14Pin = 1U << 14U, /*!< CAPT_X14 pin. */
49 kCAPT_X15Pin = 1U << 15U, /*!< CAPT_X15 pin. */
50 };
51
52 /*!
53 * @brief The enumeration for enabling/disabling interrupts.
54 */
55 enum _capt_interrupt_enable
56 {
57 kCAPT_InterruptOfYesTouchEnable =
58 CAPT_INTENSET_YESTOUCH_MASK, /*!< Generate interrupt when a touch has been detected. */
59 kCAPT_InterruptOfNoTouchEnable =
60 CAPT_INTENSET_NOTOUCH_MASK, /*!< Generate interrupt when a no-touch has been detected. */
61 kCAPT_InterruptOfPollDoneEnable = CAPT_INTENSET_POLLDONE_MASK, /*!< Genarate interrupt at the end of a polling
62 round, or when a POLLNOW completes. */
63 kCAPT_InterruptOfTimeOutEnable = CAPT_INTENSET_TIMEOUT_MASK, /*!< Generate interrupt when the count reaches the
64 time-out count value before a trigger occurs. */
65 kCAPT_InterruptOfOverRunEnable = CAPT_INTENSET_OVERUN_MASK, /*!< Generate interrupt when the Touch Data register has
66 been up-dated before software has read the previous
67 data, and the touch has been detected. */
68 };
69
70 /*!
71 * @brief The enumeration for interrupt status flags.
72 */
73 enum _capt_interrupt_status_flags
74 {
75 kCAPT_InterruptOfYesTouchStatusFlag = CAPT_INTSTAT_YESTOUCH_MASK, /*!< YESTOUCH interrupt status flag. */
76 kCAPT_InterruptOfNoTouchStatusFlag = CAPT_INTSTAT_NOTOUCH_MASK, /*!< NOTOUCH interrupt status flag. */
77 kCAPT_InterruptOfPollDoneStatusFlag = CAPT_INTSTAT_POLLDONE_MASK, /*!< POLLDONE interrupt status flag. */
78 kCAPT_InterruptOfTimeOutStatusFlag = CAPT_INTSTAT_TIMEOUT_MASK, /*!< TIMEOUT interrupt status flag. */
79 kCAPT_InterruptOfOverRunStatusFlag = CAPT_INTSTAT_OVERUN_MASK, /*!< OVERRUN interrupt status flag. */
80 };
81
82 /*!
83 * @brief The enumeration for CAPT status flags.
84 */
85 enum _capt_status_flags
86 {
87 kCAPT_BusyStatusFlag = CAPT_STATUS_BUSY_MASK, /*!< Set while a poll is currently in progress, otherwise cleared. */
88 kCAPT_XMAXStatusFlag = CAPT_STATUS_XMAX_MASK, /*!< The maximum number of X pins available for a given device is
89 equal to XMAX+1. */
90 };
91
92 /*!
93 * @brief The enumeration for CAPT trigger mode.
94 */
95 typedef enum _capt_trigger_mode
96 {
97 kCAPT_YHPortTriggerMode = 0U, /*!< YH port pin trigger mode. */
98 kCAPT_ComparatorTriggerMode = 1U, /*!< Analog comparator trigger mode. */
99 } capt_trigger_mode_t;
100
101 /*!
102 * @brief The enumeration for the inactive X pins mode.
103 */
104 typedef enum _capt_inactive_xpins_mode
105 {
106 kCAPT_InactiveXpinsHighZMode =
107 0U, /*!< Xpins enabled in the XPINSEL field are controlled to HIGH-Z mode when not active. */
108 kCAPT_InactiveXpinsDrivenLowMode =
109 1U, /*!< Xpins enabled in the XPINSEL field are controlled to be driven low mode when not active. */
110 } capt_inactive_xpins_mode_t;
111
112 /*!
113 * @brief The enumeration for the delay of measuring voltage state.
114 */
115 typedef enum _capt_measurement_delay
116 {
117 kCAPT_MeasureDelayNoWait = 0U, /*!< Don’t wait. */
118 kCAPT_MeasureDelayWait3FCLKs = 1U, /*!< Wait 3 divided FCLKs. */
119 kCAPT_MeasureDelayWait5FCLKs = 2U, /*!< Wait 5 divided FCLKs. */
120 kCAPT_MeasureDelayWait9FCLKs = 3U, /*!< Wait 9 divided FCLKs. */
121 } capt_measurement_delay_t;
122
123 /*!
124 * @brief The enumeration for the delay of reseting or draining Cap.
125 */
126 typedef enum _capt_reset_delay
127 {
128 kCAPT_ResetDelayNoWait = 0U, /*!< Don’t wait. */
129 kCAPT_ResetDelayWait3FCLKs = 1U, /*!< Wait 3 divided FCLKs. */
130 kCAPT_ResetDelayWait5FCLKs = 2U, /*!< Wait 5 divided FCLKs. */
131 kCAPT_ResetDelayWait9FCLKs = 3U, /*!< Wait 9 divided FCLKs. */
132 } capt_reset_delay_t;
133
134 /*!
135 * @brief The enumeration of CAPT polling mode.
136 */
137 typedef enum _capt_polling_mode
138 {
139 kCAPT_PollInactiveMode =
140 0U, /*!< No measurements are taken, no polls are performed. The module remains in the Reset/ Draining Cap. */
141 kCAPT_PollNowMode = 1U, /*!< Immediately launches (ignoring Poll Delay) a one-time-only, simultaneous poll of all X
142 pins that are enabled in the XPINSEL field of the Control register, then stops, returning
143 to Reset/Draining Cap. */
144 kCAPT_PollContinuousMode =
145 2U, /*!< Polling rounds are continuously performed, by walking through the enabled X pins. */
146 } capt_polling_mode_t;
147
148 /*!
149 * @brief The enumeration of CAPT DMA trigger mode.
150 */
151 typedef enum _capt_dma_mode
152 {
153 kCAPT_DMATriggerOnTouchMode = 1U, /*!< Trigger on touch. */
154 kCAPT_DMATriggerOnBothMode = 2U, /*!< Trigger on both touch and no-touch. */
155 kCAPT_DMATriggerOnAllMode = 3U, /*!< Trigger on all touch, no-touch and time-out. */
156 } capt_dma_mode_t;
157
158 /*!
159 * @brief The structure for CAPT basic configuration.
160 */
161 typedef struct _capt_config
162 {
163 bool enableWaitMode; /*!< If enable the wait mode, when the touch event occurs, the module will wait until the TOUCH
164 register is read
165 before starting the next measurement. Other-wise, measurements continue. */
166 bool enableTouchLower; /*!< enableTouchLower = true: Trigger at count < TCNT is a touch. Trigger at count > TCNT is
167 a no-touch.
168 enableTouchLower = false: Trigger at count > TCNT is a touch. Trigger at count < TCNT is
169 a no-touch.
170 Notice: TCNT will be set by "CAPT_DoCalibration" API. */
171 uint8_t clockDivider; /*!< Function clock divider. The function clock is divided by clockDivider+1 to produce the
172 divided FCLK for the module.
173 The available range is 0-15. */
174 uint8_t timeOutCount; /*!< Sets the count value at which a time-out event occurs if a measurement has not triggered.
175 The time-out count value is calculated as 2^timeOutCount. The available range is 0-12. */
176 uint8_t pollCount; /*!< Sets the time delay between polling rounds (successive sets of X measurements). After each
177 polling round completes,
178 the module will wait 4096 x PollCount divided FCLKs before starting the next polling round.
179 The available range is 0-255. */
180 uint16_t enableXpins; /*!< Selects which of the available X pins are enabled. Please refer to '_capt_xpins'.
181 For example, if want to enable X0, X2 and X3 pins, you can set "enableXpins = kCAPT_X0Pin
182 | kCAPT_X2Pin
183 | kCAPT_X3Pin". */
184 capt_trigger_mode_t
185 triggerMode; /*!< Select the menthods of measuring the voltage across the measurement capacitor. */
186 capt_inactive_xpins_mode_t
187 XpinsMode; /*!< Determines how X pins enabled in the XPINSEL field are controlled when not active. */
188 capt_measurement_delay_t mDelay; /*!< Set the time delay after entering step 3 (measure voltage state), before
189 sampling the YH port pin or analog comarator output. */
190 capt_reset_delay_t rDelay; /*!< Set the number of divided FCLKs the module will remain in Reset or Draining Cap. */
191 } capt_config_t;
192
193 /*!
194 * @brief The structure for storing touch data.
195 */
196 typedef struct _capt_touch_data
197 {
198 bool yesTimeOut; /*!< 'true': if the measurement resulted in a time-out event, 'false': otherwise. */
199 bool yesTouch; /*!< 'true': if the trigger is due to a touch even, 'false': if the trigger is due to a no-touch
200 event. */
201 uint8_t XpinsIndex; /*!< Contains the index of the X pin for the current measurement, or lowest X for a
202 multiple-pin poll now measurement. */
203 uint8_t sequenceNumber; /*!< Contains the 4-bit(0-7) sequence number, which increments at the end of each polling
204 round. */
205 uint16_t count; /*!< Contains the count value reached at trigger or time-out. */
206 } capt_touch_data_t;
207
208 /*******************************************************************************
209 * API
210 ******************************************************************************/
211 #if defined(__cplusplus)
212 extern "C" {
213 #endif /* __cplusplus*/
214
215 /*!
216 * @name Initialization
217 * @{
218 */
219
220 /*!
221 * @brief Initialize the CAPT module.
222 *
223 * @param base CAPT peripheral base address.
224 * @param config Pointer to "capt_config_t" structure.
225 */
226 void CAPT_Init(CAPT_Type *base, const capt_config_t *config);
227
228 /*!
229 * @brief De-initialize the CAPT module.
230 *
231 * @param base CAPT peripheral base address.
232 */
233 void CAPT_Deinit(CAPT_Type *base);
234
235 /*!
236 * @brief Gets an available pre-defined settings for the CAPT's configuration.
237 *
238 * This function initializes the converter configuration structure with available settings. The default values are:
239 * @code
240 * config->enableWaitMode = false;
241 * config->enableTouchLower = true;
242 * config->clockDivider = 15U;
243 * config->timeOutCount = 12U;
244 * config->pollCount = 0U;
245 * config->enableXpins = 0U;
246 * config->triggerMode = kCAPT_YHPortTriggerMode;
247 * config->XpinsMode = kCAPT_InactiveXpinsDrivenLowMode;
248 * config->mDelay = kCAPT_MeasureDelayNoWait;
249 * config->rDelay = kCAPT_ResetDelayWait9FCLKs;
250 * @endcode
251 * @param config Pointer to the configuration structure.
252 */
253 void CAPT_GetDefaultConfig(capt_config_t *config);
254
255 /*!
256 * @brief Set Sets the count threshold in divided FCLKs between touch and no-touch.
257 *
258 * @param base CAPT peripheral base address.
259 * @param count The count threshold.
260 */
CAPT_SetThreshold(CAPT_Type * base,uint32_t count)261 static inline void CAPT_SetThreshold(CAPT_Type *base, uint32_t count)
262 {
263 base->POLL_TCNT = ((base->POLL_TCNT & ~CAPT_POLL_TCNT_TCNT_MASK) | CAPT_POLL_TCNT_TCNT(count));
264 }
265
266 /*!
267 * @brief Set the CAPT polling mode.
268 *
269 * @param base CAPT peripheral base address.
270 * @param mode The selection of polling mode.
271 */
272 void CAPT_SetPollMode(CAPT_Type *base, capt_polling_mode_t mode);
273
274 #if defined(FSL_FEATURE_CAPT_HAS_CTRL_DMA) && FSL_FEATURE_CAPT_HAS_CTRL_DMA
275 /*!
276 * @brief Enable DMA feature.
277 *
278 * @param base CAPT peripheral base address.
279 * @param mode Select how DMA triggers are generated.
280 */
281 void CAPT_EnableDMA(CAPT_Type *base, capt_dma_mode_t mode);
282
283 /*!
284 * @brief Disable DMA feature.
285 *
286 * @param base CAPT peripheral base address.
287 */
288 void CAPT_DisableDMA(CAPT_Type *base);
289 #endif /*FSL_FEATURE_CAPT_HAS_CTRL_DMA*/
290
291 /*!
292 * @brief Enable interrupt features.
293 *
294 * @param base CAPT peripheral base address.
295 * @param mask The mask of enabling interrupt features. Please refer to "_capt_interrupt_enable".
296 */
CAPT_EnableInterrupts(CAPT_Type * base,uint32_t mask)297 static inline void CAPT_EnableInterrupts(CAPT_Type *base, uint32_t mask)
298 {
299 base->INTENSET = mask;
300 }
301
302 /*!
303 * @brief Disable interrupt features.
304 *
305 * @param base CAPT peripheral base address.
306 * @param mask The mask of disabling interrupt features. Please refer to "_capt_interrupt_enable".
307 */
CAPT_DisableInterrupts(CAPT_Type * base,uint32_t mask)308 static inline void CAPT_DisableInterrupts(CAPT_Type *base, uint32_t mask)
309 {
310 base->INTENCLR = mask;
311 }
312
313 /*!
314 * @brief Get CAPT interrupts' status flags.
315 *
316 * @param base CAPT peripheral base address.
317 * @return The mask of interrupts' status flags. please refer to "_capt_interrupt_status_flags".
318 */
CAPT_GetInterruptStatusFlags(CAPT_Type * base)319 static inline uint32_t CAPT_GetInterruptStatusFlags(CAPT_Type *base)
320 {
321 return base->INTSTAT;
322 }
323
324 /*!
325 * @brief Clear the interrupts' status flags.
326 *
327 * @param base CAPT peripheral base address.
328 * @param mask The mask of clearing the interrupts' status flags, please refer to "_capt_interrupt_status_flags".
329 */
CAPT_ClearInterruptStatusFlags(CAPT_Type * base,uint32_t mask)330 static inline void CAPT_ClearInterruptStatusFlags(CAPT_Type *base, uint32_t mask)
331 {
332 base->STATUS = mask;
333 }
334
335 /*!
336 * @brief Get CAPT status flags.
337 *
338 * @param base CAPT peripheral base address.
339 * @return The mask of CAPT status flags. Please refer to "_capt_status_flags"
340 * Or use CAPT_GET_XMAX_NUMBER(mask) to get XMAX number.
341 */
CAPT_GetStatusFlags(CAPT_Type * base)342 static inline uint32_t CAPT_GetStatusFlags(CAPT_Type *base)
343 {
344 return base->STATUS;
345 }
346
347 /*!
348 * @brief Get CAPT touch data.
349 *
350 * @param base CAPT peripheral base address.
351 * @param data The structure to store touch data.
352 *
353 * @return If return 'true', which means get valid data.
354 * if return 'false', which means get invalid data.
355 */
356 bool CAPT_GetTouchData(CAPT_Type *base, capt_touch_data_t *data);
357
358 /*!
359 * @brief Start touch data polling using poll-now method.
360 *
361 * This function starts new data polling using polling-now method, CAPT stops when
362 * the polling is finished, application could check the status or monitor interrupt
363 * to know when the progress is finished.
364 *
365 * Note that this is simultaneous poll of all X pins, all enabled X pins are
366 * activated concurrently, rather than walked one-at-a-time
367 *
368 * @param base CAPT peripheral base address.
369 * @param enableXpins The X pins enabled in this polling.
370 */
371 void CAPT_PollNow(CAPT_Type *base, uint16_t enableXpins);
372
373 /*@}*/
374
375 #if defined(__cplusplus)
376 }
377 #endif /* __cplusplus*/
378
379 /*@}*/
380
381 #endif /* _FSL_CAPT_H_ */
382
