| Xmega IEC60730 Class B Library 1.0 |

All Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
classb_freq.h
Go to the documentation of this file.
1 /* This file has been prepared for Doxygen automatic documentation generation.*/
2 /**
3 * \file
4 *
5 * \brief
6 * Settings and definitions for the CPU frequency test.
7 *
8 * \par Application note:
9 * AVR1610: Guide to IEC60730 Class B compliance with XMEGA
10 *
11 * \par Documentation
12 * For comprehensive code documentation, supported compilers, compiler
13 * settings and supported devices see readme.html
14 *
15 * \author
16 * Atmel Corporation: http://www.atmel.com \n
17 * Support email: avr@atmel.com
18 *
19 * Copyright (C) 2012 Atmel Corporation. All rights reserved.
20 *
21 * \page License
22 *
23 * Redistribution and use in source and binary forms, with or without
24 * modification, are permitted provided that the following conditions are met:
25 *
26 * 1. Redistributions of source code must retain the above copyright notice,
27 * this list of conditions and the following disclaimer.
28 *
29 * 2. Redistributions in binary form must reproduce the above copyright notice,
30 * this list of conditions and the following disclaimer in the documentation
31 * and/or other materials provided with the distribution.
32 *
33 * 3. The name of Atmel may not be used to endorse or promote products derived
34 * from this software without specific prior written permission.
35 *
36 * 4. This software may only be redistributed and used in connection with an
37 * Atmel AVR product.
38 *
39 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
40 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
41 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
42 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
43 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
44 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
45 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
46 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
47 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
48 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
49 * DAMAGE.
50 */
51
52 #ifndef TEST_CPU_VS_RTC_H_
53 #define TEST_CPU_VS_RTC_H_
54
55 #include "avr_compiler.h"
56 #include "classb_rtc_common.h"
57 #include "error_handler.h"
58
59
60 //! \defgroup cpu_freq CPU Frequency Test
61 //!
62 //! \brief This is the self-diagnostic test for the CPU frequency. The test
63 //! consists in monitoring the frequency of a Timer/Counter (TC) using the
64 //! Real Time Counter (RTC) module as a time reference. Note that the TC
65 //! has the same clock domain as the CPU and that the RTC module in XMEGA
66 //! can have a clock source independent from the CPU clock domain. Note that
67 //! \ref CLASSB_FREQ_TEST has to be defined. For more details see \ref rtc_driver.
68 //!
69 //! The test is implemented as follows. Firstly, an RTC compare interrupt
70 //! is scheduled periodically with \ref classb_rtc_setup() and a TC is
71 //! started with \ref classb_freq_setup_timer(). Secondly, the RTC interrupt
72 //! calls \ref classb_freq_callback(), which compares the absolute difference
73 //! between the count in the TC and a predefined reference. If it should be
74 //! greater than expected, the error handler \ref CLASSB_ERROR_HANDLER_FREQ()
75 //! would be called.
76 //!
77 //! The TC overflow interrupt increases a counter that can be used as
78 //! most significant word (bits 31 to 16) for the TC counter value.
79 //! Further, there is a configurable limit for the number of overflows.
80 //! If this was exceeded, the program would assume that the RTC was not
81 //! working correctly and the error handler would be called as well.
82 //!
83 //! The test is flexible and it is possible to choose some settings for the
84 //! TC and RTC. However, it is important to choose values for \ref CLASSB_RTC_INT_PERIOD,
85 //! \ref CLASSB_RTC_FREQ, \ref CLASSB_TC_PRESCALER and \ref CLASSB_TOLERANCE so that the frequency of
86 //! the CPU \ref F_CPU is estimated reliably. Further, there should not be an
87 //! overflow in \ref CLASSB_TC_COUNT_REF. Suggested values have been included in the
88 //! documentation.
89 //!
90
91 //! \addtogroup cpu_freq
92 //@{
93
94
95 //! \defgroup freq_conf Settings
96 //! \brief This should be configured by the user
97 //@{
98
99 #ifdef __DOXYGEN__
100 //! \brief The system frequency.
101 //!
102 //! This is the expected frequency (Hz) of the CPU. This value has to be defined at
103 //! the compiler level and it is only used to compute the TC count
104 //! reference, i.e. not to set the system clock. Therefore,
105 //! this value should be consistent with the system clock settings in the main
106 //! application. However, this constant could be used to test the self-diagnostic routine,
107 //! i.e. a wrong value could be set to check whether the failure is detected.
108 //! \note The system runs from the internal 2Mhz RC oscillator by default.
109 #define F_CPU <value>
110 #endif
111
112 //! \brief TC module selection
113 //!
114 //! This is the number of the TC module that should be used for the CPU frequency
115 //! test, e.g. 0 -> TCC0.
116 #define CLASSB_TC_MOD 0
117
118 //!\brief TC prescaler
119 //!
120 //! The TC runs on the system clock scaled down by this parameter.
121 //! Possible values are 1, 2, 4, 8, 64, 256 or 1024.
122 #define CLASSB_TC_PRESCALER 8
123
124 //! \brief Tolerance for the CPU frequency deviation
125 //!
126 //! This value defines the tolerance (an integer, %) for the deviation between the measured
127 //! and expected CPU, e.g. 25 -> 25%.
128 #define CLASSB_TOLERANCE 25UL
129
130 //@}
131
132
133 //! \internal \defgroup int_conf_freq Internal settings
134 //!
135 //! \brief This constants should not be modified.
136 //@{
137
138 //! \internal \brief Label for the TC module
139 #define CLASSB_TEST_TC LABEL(TCC, CLASSB_TC_MOD,)
140
141 //! \internal \brief Label for the overflow interrupt vector for the chosen TC
142 #define CLASSB_TEST_TC_OVF_vect LABEL(TCC, CLASSB_TC_MOD, _OVF_vect)
143
144 //! \internal \brief Label for the TC prescaler group configuration
145 #define CLASSB_TC_PRESCALER_gc LABEL(TC_CLKSEL_DIV, CLASSB_TC_PRESCALER, _gc)
146
147 //! \internal \brief TC period
148 //!
149 //! The 16-bit TC will generate an interrupt when the count reaches this value.
150 //! The code is built counting that this is the largest possible value, i.e. 0xFFFF.
151 #define CLASSB_TC_PER 0xFFFF
152
153 //! \internal \brief TC frequency
154 //!
155 //! The frequency of the TC is F_CPU divided by the prescaling factor.
156 #define CLASSB_TC_FREQ (uint32_t) (F_CPU/CLASSB_TC_PRESCALER)
157
158 //! \internal \brief TC count reference
159 //!
160 //! This is the reference value for TC count within one RTC interrupt period.
161 //! Reference = F_tc * Interrupt_Period_rtc / F_rtc
162 //! This can overflow if \ref CLASSB_TC_FREQ and \ref CLASSB_RTC_INT_PERIOD are too large.
163 //! Note that multiplying by 1e0L forces the preprocessor to do operations with
164 //! higher precision.
165 #define CLASSB_TC_COUNT_REF (uint32_t) ( ( (1e0L * CLASSB_TC_FREQ) * CLASSB_RTC_INT_PERIOD) / CLASSB_RTC_FREQ )
166
167 //! \internal \brief Maximum absolute difference between the reference and estimated frequencies
168 //!
169 //! Note that multiplying by 1e0L forces the preprocessor to do operations with
170 //! higher precision.<
171 #define CLASSB_MAX_DIF (uint32_t) ( (1e0L * CLASSB_TC_COUNT_REF * CLASSB_TOLERANCE) / 100UL )
172
173 //! \internal \brief TC maximum number of overflows
174 //!
175 //! This is a limit for the number of TC overflows. If this should be exceeded the RTC
176 //! would be assumed to be faulty and the error handler would be called.
177 #define CLASSB_COUNT_OVF_MAX (uint16_t) ( ( CLASSB_TC_COUNT_REF + CLASSB_MAX_DIF )>> 16)
178
179 //@}
180
181
182 //! \defgroup func_freq Functions
183 //!
184 //! \brief Functions related to the CPU frequency self-test.
185 //@{
186 void classb_freq_setup_timer();
187 void classb_freq_callback();
188 //@}
189
190
191 //@}
192
193 #endif /* TEST_CPU_VS_RTC_H_ */