ChibiOS/HAL  6.1.0
hal_icu.h
Go to the documentation of this file.
1 /*
2  ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3 
4  Licensed under the Apache License, Version 2.0 (the "License");
5  you may not use this file except in compliance with the License.
6  You may obtain a copy of the License at
7 
8  http://www.apache.org/licenses/LICENSE-2.0
9 
10  Unless required by applicable law or agreed to in writing, software
11  distributed under the License is distributed on an "AS IS" BASIS,
12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  See the License for the specific language governing permissions and
14  limitations under the License.
15 */
16 
17 /**
18  * @file hal_icu.h
19  * @brief ICU Driver macros and structures.
20  *
21  * @addtogroup ICU
22  * @{
23  */
24 
25 #ifndef HAL_ICU_H
26 #define HAL_ICU_H
27 
28 #if (HAL_USE_ICU == TRUE) || defined(__DOXYGEN__)
29 
30 /*===========================================================================*/
31 /* Driver constants. */
32 /*===========================================================================*/
33 
34 /*===========================================================================*/
35 /* Driver pre-compile time settings. */
36 /*===========================================================================*/
37 
38 /*===========================================================================*/
39 /* Derived constants and error checks. */
40 /*===========================================================================*/
41 
42 /*===========================================================================*/
43 /* Driver data structures and types. */
44 /*===========================================================================*/
45 
46 /**
47  * @brief Driver state machine possible states.
48  */
49 typedef enum {
50  ICU_UNINIT = 0, /**< Not initialized. */
51  ICU_STOP = 1, /**< Stopped. */
52  ICU_READY = 2, /**< Ready. */
53  ICU_WAITING = 3, /**< Waiting for first front. */
54  ICU_ACTIVE = 4 /**< First front detected. */
55 } icustate_t;
56 
57 /**
58  * @brief Type of a structure representing an ICU driver.
59  */
60 typedef struct ICUDriver ICUDriver;
61 
62 /**
63  * @brief ICU notification callback type.
64  *
65  * @param[in] icup pointer to a @p ICUDriver object
66  */
67 typedef void (*icucallback_t)(ICUDriver *icup);
68 
69 #include "hal_icu_lld.h"
70 
71 /*===========================================================================*/
72 /* Driver macros. */
73 /*===========================================================================*/
74 
75 /**
76  * @name Macro Functions
77  * @{
78  */
79 /**
80  * @brief Starts the input capture.
81  *
82  * @param[in] icup pointer to the @p ICUDriver object
83  *
84  * @iclass
85  */
86 #define icuStartCaptureI(icup) do { \
87  icu_lld_start_capture(icup); \
88  (icup)->state = ICU_WAITING; \
89 } while (false)
90 
91 /**
92  * @brief Stops the input capture.
93  *
94  * @param[in] icup pointer to the @p ICUDriver object
95  *
96  * @iclass
97  */
98 #define icuStopCaptureI(icup) do { \
99  icu_lld_stop_capture(icup); \
100  (icup)->state = ICU_READY; \
101 } while (false)
102 
103 /**
104  * @brief Enables notifications.
105  * @pre The ICU unit must have been activated using @p icuStart() and the
106  * capture started using @p icuStartCapture().
107  * @note If the notification is already enabled then the call has no effect.
108  *
109  * @param[in] icup pointer to the @p ICUDriver object
110  *
111  * @iclass
112  */
113 #define icuEnableNotificationsI(icup) icu_lld_enable_notifications(icup)
114 
115 /**
116  * @brief Disables notifications.
117  * @pre The ICU unit must have been activated using @p icuStart() and the
118  * capture started using @p icuStartCapture().
119  * @note If the notification is already disabled then the call has no effect.
120  *
121  * @param[in] icup pointer to the @p ICUDriver object
122  *
123  * @iclass
124  */
125 #define icuDisableNotificationsI(icup) icu_lld_disable_notifications(icup)
126 
127 /**
128  * @brief Check on notifications status.
129  *
130  * @param[in] icup pointer to the @p ICUDriver object
131  * @return The notifications status.
132  * @retval false if notifications are not enabled.
133  * @retval true if notifications are enabled.
134  *
135  * @notapi
136  */
137 #define icuAreNotificationsEnabledX(icup) \
138  icu_lld_are_notifications_enabled(icup)
139 
140 /**
141  * @brief Returns the width of the latest pulse.
142  * @details The pulse width is defined as number of ticks between the start
143  * edge and the stop edge.
144  * @note This function is meant to be invoked from the width capture
145  * callback.
146  *
147  * @param[in] icup pointer to the @p ICUDriver object
148  * @return The number of ticks.
149  *
150  * @xclass
151  */
152 #define icuGetWidthX(icup) icu_lld_get_width(icup)
153 
154 /**
155  * @brief Returns the width of the latest cycle.
156  * @details The cycle width is defined as number of ticks between a start
157  * edge and the next start edge.
158  * @note This function is meant to be invoked from the width capture
159  * callback.
160  *
161  * @param[in] icup pointer to the @p ICUDriver object
162  * @return The number of ticks.
163  *
164  * @xclass
165  */
166 #define icuGetPeriodX(icup) icu_lld_get_period(icup)
167 /** @} */
168 
169 /**
170  * @name Low level driver helper macros
171  * @{
172  */
173 /**
174  * @brief Common ISR code, ICU width event.
175  *
176  * @param[in] icup pointer to the @p ICUDriver object
177  *
178  * @notapi
179  */
180 #define _icu_isr_invoke_width_cb(icup) do { \
181  if (((icup)->state == ICU_ACTIVE) && \
182  ((icup)->config->width_cb != NULL)) \
183  (icup)->config->width_cb(icup); \
184 } while (0)
185 
186 /**
187  * @brief Common ISR code, ICU period event.
188  * @note A period event brings the driver into the @p ICU_ACTIVE state.
189  *
190  * @param[in] icup pointer to the @p ICUDriver object
191  *
192  * @notapi
193  */
194 #define _icu_isr_invoke_period_cb(icup) do { \
195  if (((icup)->state == ICU_ACTIVE) && \
196  ((icup)->config->period_cb != NULL)) \
197  (icup)->config->period_cb(icup); \
198  (icup)->state = ICU_ACTIVE; \
199 } while (0)
200 
201 /**
202  * @brief Common ISR code, ICU timer overflow event.
203  * @note An overflow always brings the driver back to the @p ICU_WAITING
204  * state.
205  *
206  * @param[in] icup pointer to the @p ICUDriver object
207  *
208  * @notapi
209  */
210 #define _icu_isr_invoke_overflow_cb(icup) do { \
211  (icup)->config->overflow_cb(icup); \
212  (icup)->state = ICU_WAITING; \
213 } while (0)
214 /** @} */
215 
216 /*===========================================================================*/
217 /* External declarations. */
218 /*===========================================================================*/
219 
220 #ifdef __cplusplus
221 extern "C" {
222 #endif
223  void icuInit(void);
224  void icuObjectInit(ICUDriver *icup);
225  void icuStart(ICUDriver *icup, const ICUConfig *config);
226  void icuStop(ICUDriver *icup);
227  void icuStartCapture(ICUDriver *icup);
228  bool icuWaitCapture(ICUDriver *icup);
229  void icuStopCapture(ICUDriver *icup);
230  void icuEnableNotifications(ICUDriver *icup);
232 #ifdef __cplusplus
233 }
234 #endif
235 
236 #endif /* HAL_USE_ICU == TRUE */
237 
238 #endif /* HAL_ICU_H */
239 
240 /** @} */
void icuObjectInit(ICUDriver *icup)
Initializes the standard part of a ICUDriver structure.
Definition: hal_icu.c:68
PLATFORM ICU subsystem low level driver header.
void icuInit(void)
ICU Driver initialization.
Definition: hal_icu.c:56
Driver configuration structure.
Definition: hal_icu_lld.h:82
Structure representing an ICU driver.
Definition: hal_icu_lld.h:111
icustate_t
Driver state machine possible states.
Definition: hal_icu.h:49
void icuStopCapture(ICUDriver *icup)
Stops the input capture.
Definition: hal_icu.c:175
void icuStartCapture(ICUDriver *icup)
Starts the input capture.
Definition: hal_icu.c:125
bool icuWaitCapture(ICUDriver *icup)
Waits for a completed capture.
Definition: hal_icu.c:151
const ICUConfig * config
Current configuration data.
Definition: hal_icu_lld.h:119
void icuDisableNotifications(ICUDriver *icup)
Disables notifications.
Definition: hal_icu.c:218
void icuStart(ICUDriver *icup, const ICUConfig *config)
Configures and activates the ICU peripheral.
Definition: hal_icu.c:82
void icuEnableNotifications(ICUDriver *icup)
Enables notifications.
Definition: hal_icu.c:197
void icuStop(ICUDriver *icup)
Deactivates the ICU peripheral.
Definition: hal_icu.c:102
void(* icucallback_t)(ICUDriver *icup)
ICU notification callback type.
Definition: hal_icu.h:67