1 /**
2 * \file
3 *
4 * \brief SAM Frequency Meter (FREQM) Driver
5 *
6 * Copyright (C) 2015-2016 Atmel Corporation. All rights reserved.
7 *
8 * \asf_license_start
9 *
10 * \page License
11 *
12 * Redistribution and use in source and binary forms, with or without
13 * modification, are permitted provided that the following conditions are met:
14 *
15 * 1. Redistributions of source code must retain the above copyright notice,
16 * this list of conditions and the following disclaimer.
17 *
18 * 2. Redistributions in binary form must reproduce the above copyright notice,
19 * this list of conditions and the following disclaimer in the documentation
20 * and/or other materials provided with the distribution.
21 *
22 * 3. The name of Atmel may not be used to endorse or promote products derived
23 * from this software without specific prior written permission.
24 *
25 * 4. This software may only be redistributed and used in connection with an
26 * Atmel microcontroller product.
27 *
28 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
29 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
31 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
32 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
33 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
34 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
35 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
36 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38 * POSSIBILITY OF SUCH DAMAGE.
39 *
40 * \asf_license_stop
41 *
42 */
43 /*
44 * Support and FAQ: visit <a href="http://www.atmel.com/design-support/">Atmel Support</a>
45 */
46
47 #ifndef FREQM_H_INCLUDED
48 #define FREQM_H_INCLUDED
49
50 /**
51 * \defgroup asfdoc_sam0_freqm_group SAM Frequency Meter (FREQM) Driver
52 *
53 * This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration
54 * and management of the device's Frequency Meter functionality.
55 *
56 * The following driver API modes are covered by this manual:
57 * - Polled APIs
58 * \if FREQM_CALLBACK_MODE
59 * - Callback APIs
60 * \endif
61 *
62 * The following peripheral is used by this module:
63 * - FREQM (Frequency Meter)
64 *
65 * The following devices can use this module:
66 * - Atmel | SMART SAM L22
67 * - Atmel | SMART SAM C20
68 * - Atmel | SMART SAM C21
69 *
70 * The outline of this documentation is as follows:
71 * - \ref asfdoc_sam0_freqm_prerequisites
72 * - \ref asfdoc_sam0_freqm_module_overview
73 * - \ref asfdoc_sam0_freqm_special_considerations
74 * - \ref asfdoc_sam0_freqm_extra_info
75 * - \ref asfdoc_sam0_freqm_examples
76 * - \ref asfdoc_sam0_freqm_api_overview
77 *
78 *
79 * \section asfdoc_sam0_freqm_prerequisites Prerequisites
80 *
81 * There are no prerequisites for this module.
82 *
83 *
84 * \section asfdoc_sam0_freqm_module_overview Module Overview
85 *
86 * The module accurately measures the frequency of a clock by comparing it to a
87 * known reference clock as soon as the FREQM is enabled. Two generic clocks are
88 * used by the FREQM. The frequency of the measured clock is:
89 * \f[
90 * f_{CLK\_MSR} = \frac{VALUE}{REFNUM} \times f_{CLK\_REF}
91 * \f]
92 * Ratio can be measured with 24-bit accuracy.
93 *
94 * The FREQM has one interrupt source, which generates when a frequency measurement
95 * is done. It can be used to wake up the device from sleep modes.
96 *
97 * This driver provides an interface for the FREQM functions on the device.
98 *
99 * \section asfdoc_sam0_freqm_special_considerations Special Considerations
100 *
101 * There are no special considerations for this module.
102 *
103 *
104 * \section asfdoc_sam0_freqm_extra_info Extra Information
105 *
106 * For extra information see \ref asfdoc_sam0_freqm_extra. This includes:
107 * - \ref asfdoc_sam0_freqm_extra_acronyms
108 * - \ref asfdoc_sam0_freqm_extra_dependencies
109 * - \ref asfdoc_sam0_freqm_extra_errata
110 * - \ref asfdoc_sam0_freqm_extra_history
111 *
112 *
113 * \section asfdoc_sam0_freqm_examples Examples
114 *
115 * For a list of examples related to this driver, see
116 * \ref asfdoc_sam0_freqm_exqsg.
117 *
118 *
119 * \section asfdoc_sam0_freqm_api_overview API Overview
120 * @{
121 */
122
123 #include <compiler.h>
124 #include <system.h>
125
126 #ifdef __cplusplus
127 extern "C" {
128 #endif
129
130 #if FREQM_CALLBACK_MODE == true
131 /** Forward declaration of struct */
132 struct freqm_module;
133
134 extern struct freqm_module *_freqm_instance;
135
136 /** Type definition for a FREQM module callback function. */
137 typedef void (*freqm_callback_t)(void);
138
139 /** Enum for possible callback types for the FREQM module. */
140 enum freqm_callback {
141 /** Callback for measurement done */
142 FREQM_CALLBACK_DONE = 0,
143 /** Number of available callbacks */
144 #if !defined(__DOXYGEN__)
145 FREQM_CALLBACK_N,
146 #endif
147 };
148 #endif
149
150 /**
151 * \brief FREQM software device instance structure.
152 *
153 * FREQM software instance structure, used to retain software state information
154 * of an associated hardware module instance.
155 *
156 * \note The fields of this structure should not be altered by the user
157 * application; they are reserved for module-internal use only.
158 */
159 struct freqm_module {
160 #if !defined(__DOXYGEN__)
161 /** Hardware module pointer of the associated FREQM peripheral */
162 Freqm *hw;
163 /** The frequency of reference clock in Hz*/
164 uint32_t ref_clock_freq;
165 # if FREQM_CALLBACK_MODE == true
166 /** Array of callbacks */
167 freqm_callback_t callback[FREQM_CALLBACK_N];
168 # endif
169 #endif
170 };
171
172 /** Enum for the possible status types for the FREQM module. */
173 enum freqm_status {
174 /** FREQM measurement is finish */
175 FREQM_STATUS_MEASURE_DONE = 0,
176 /** FREQM measurement is ongoing or not */
177 FREQM_STATUS_MEASURE_BUSY = 1,
178 /** FREQM sticky count value overflow */
179 FREQM_STATUS_CNT_OVERFLOW = 2,
180 };
181
182 /**
183 * \brief FREQM module configuration structure.
184 *
185 * Configuration structure for a Frequency Meter.
186 */
187 struct freqm_config {
188 /** GCLK source select for measurement */
189 enum gclk_generator msr_clock_source;
190 /** GCLK source select for reference */
191 enum gclk_generator ref_clock_source;
192 /** Measurement duration in number of reference clock cycles. Range 1~255 */
193 uint16_t ref_clock_circles;
194 };
195
196 /**
197 * \brief Determines if the hardware module(s) are currently synchronizing to the bus.
198 *
199 * Checks to see if the underlying hardware peripheral module(s) are currently
200 * synchronizing across multiple clock domains to the hardware bus. This
201 * function can be used to delay further operations on a module until such time
202 * that it is ready, to prevent blocking delays for synchronization in the
203 * user application.
204 *
205 * \return Synchronization status of the underlying hardware module(s).
206 *
207 * \retval false If the module has completed synchronization
208 * \retval true If the module synchronization is ongoing
209 */
freqm_is_syncing(void)210 static inline bool freqm_is_syncing(void)
211 {
212 Freqm *const freqm_module = FREQM;
213
214 if (freqm_module->SYNCBUSY.reg) {
215 return true;
216 }
217
218 return false;
219 }
220
221 /**
222 * \name Driver Initialization and Configuration
223 * @{
224 */
225 enum status_code freqm_init(
226 struct freqm_module *const module_inst,
227 Freqm *const hw,
228 struct freqm_config *const config);
229
230 /**
231 * \brief Initializes all members of a FREQM configuration structure
232 * to safe defaults.
233 *
234 * Initializes all members of a given Frequency Meter configuration
235 * structure to safe known default values. This function should be called on
236 * all new instances of these configuration structures before being modified
237 * by the user application.
238 *
239 * The default configuration is as follows:
240 * \li Measurement clock source is GCLK0
241 * \li Reference clock source is GCLK1
242 * \li Frequency Meter Reference Clock Cycles 127
243 *
244 * \param[in] config Configuration structure to initialize to default values
245 */
freqm_get_config_defaults(struct freqm_config * const config)246 static inline void freqm_get_config_defaults(
247 struct freqm_config *const config)
248 {
249 /* Sanity check arguments */
250 Assert(config);
251
252 /* Default configuration values */
253 config->msr_clock_source = GCLK_GENERATOR_0;
254 config->ref_clock_source = GCLK_GENERATOR_1;
255 config->ref_clock_circles = 127;
256 }
257
258 /**
259 * \brief Enables a FREQM that was previously configured.
260 *
261 * Enables Frequency Meter that was previously configured via a
262 * call to \ref freqm_init().
263 *
264 * \param[in] module_inst Software instance for the Frequency Meter peripheral
265 */
freqm_enable(struct freqm_module * const module_inst)266 static inline void freqm_enable(
267 struct freqm_module *const module_inst)
268 {
269 /* Sanity check arguments */
270 Assert(module_inst);
271 Assert(module_inst->hw);
272
273 Freqm *const freqm_module = module_inst->hw;
274
275 /* Enable FREQM */
276 freqm_module->CTRLA.reg |= FREQM_CTRLA_ENABLE;
277
278 while (freqm_is_syncing()) {
279 /* Wait for all hardware modules to complete synchronization */
280 }
281 }
282
283 /**
284 * \brief Disables a FREQM that was previously enabled.
285 *
286 * Disables Frequency Meter that was previously started via a call
287 * to \ref freqm_enable().
288 *
289 * \param[in] module_inst Software instance for the Frequency Meter peripheral
290 */
freqm_disable(struct freqm_module * const module_inst)291 static inline void freqm_disable(
292 struct freqm_module *const module_inst)
293 {
294 /* Sanity check arguments */
295 Assert(module_inst);
296 Assert(module_inst->hw);
297
298 Freqm *const freqm_module = module_inst->hw;
299
300 /* Disbale interrupt */
301 freqm_module->INTENCLR.reg = FREQM_INTENCLR_MASK;
302 /* Clear interrupt flag */
303 freqm_module->INTFLAG.reg = FREQM_INTFLAG_MASK;
304
305 /* Disable FREQM */
306 freqm_module->CTRLA.reg &= ~FREQM_CTRLA_ENABLE;
307
308 while (freqm_is_syncing()) {
309 /* Wait for all hardware modules to complete synchronization */
310 }
311 }
312
313 /** @} */
314
315 /**
316 * \name Read FREQM Result
317 * @{
318 */
319 /**
320 * \brief Start a manual measurement process.
321 *
322 * \param[in] module Pointer to the FREQM software instance struct
323 */
freqm_start_measure(struct freqm_module * const module)324 static inline void freqm_start_measure(struct freqm_module *const module)
325 {
326 /* Sanity check arguments */
327 Assert(module);
328 Assert(module->hw);
329
330 /* Trigger measurement */
331 module->hw->CTRLB.reg |= FREQM_CTRLB_START;
332 }
333
334 /**
335 * \brief Clears module overflow flag.
336 *
337 * Clears the overflow flag of the module.
338 *
339 * \param[in] module Pointer to the FREQM software instance struct
340 */
freqm_clear_overflow(struct freqm_module * const module)341 static inline void freqm_clear_overflow(struct freqm_module *const module)
342 {
343 /* Sanity check arguments */
344 Assert(module);
345 Assert(module->hw);
346
347 /* Clear overflow flag */
348 module->hw->STATUS.reg = FREQM_STATUS_OVF;
349 }
350
351 enum freqm_status freqm_get_result_value(
352 struct freqm_module *const module_inst, uint32_t *result);
353
354 /** @} */
355
356 #ifdef __cplusplus
357 }
358 #endif
359 /** @} */
360
361
362 /**
363 * \page asfdoc_sam0_freqm_extra Extra Information for FREQM Driver
364 *
365 * \section asfdoc_sam0_freqm_extra_acronyms Acronyms
366 * Below is a table listing the acronyms used in this module, along with their
367 * intended meanings.
368 *
369 * <table>
370 * <tr>
371 * <th>Acronym</th>
372 * <th>Description</th>
373 * </tr>
374 * <tr>
375 * <td>FREQM</td>
376 * <td>Frequency Meter</td>
377 * </tr>
378 * </table>
379 *
380 *
381 * \section asfdoc_sam0_freqm_extra_dependencies Dependencies
382 * This driver has no dependencies.
383 *
384 *
385 * \section asfdoc_sam0_freqm_extra_errata Errata
386 * There are no errata related to this driver.
387 *
388 *
389 * \section asfdoc_sam0_freqm_extra_history Module History
390 * An overview of the module history is presented in the table below, with
391 * details on the enhancements and fixes made to the module since its first
392 * release. The current version of this corresponds to the newest version in
393 * the table.
394 *
395 * <table>
396 * <tr>
397 * <th>Changelog</th>
398 * </tr>
399 * <tr>
400 * <td>Initial Release</td>
401 * </tr>
402 * </table>
403 */
404
405 /**
406 * \page asfdoc_sam0_freqm_exqsg Examples for FREQM Driver
407 *
408 * This is a list of the available Quick Start guides (QSGs) and example
409 * applications for \ref asfdoc_sam0_freqm_group. QSGs are simple examples with
410 * step-by-step instructions to configure and use this driver in a selection of
411 * use cases. Note that a QSG can be compiled as a standalone application or be
412 * added to the user application.
413 *
414 * - \subpage asfdoc_sam0_freqm_basic_use_case
415 * \if FREQM_CALLBACK_MODE
416 * - \subpage asfdoc_sam0_freqm_basic_use_case_callback
417 * \endif
418 *
419 * \page asfdoc_sam0_freqm_document_revision_history Document Revision History
420 *
421 * <table>
422 * <tr>
423 * <th>Doc. Rev.</td>
424 * <th>Date</td>
425 * <th>Comments</td>
426 * </tr>
427 * <tr>
428 * <td>42506A</td>
429 * <td>08/2015</td>
430 * <td>Initial document release</td>
431 * </tr>
432 * </table>
433 */
434
435 #endif /* FREQM_H_INCLUDED */
436
437