| Xmega IEC60730 Class B Library 1.0 |

All Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
classb_interrupt_monitor.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 * This file contains settings and definitions for the interrupt monitor.
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 CLASSB_INTERRUPT_MONITOR_H_
53 #define CLASSB_INTERRUPT_MONITOR_H_
54
55 #include "avr_compiler.h"
56 #include "classb_rtc_common.h"
57 #include "error_handler.h"
58
59
60 //! \defgroup int_monitor Interrupt Monitor
61 //!
62 //! \brief A test for the frequency of interrupts.
63 //!
64 //! Each time an interrupt is executed a counter is increased. The interrupt monitor
65 //! is executed periodically to check that the counters are within a configurable range.
66 //! The Real Time Counter is used to run \ref classb_intmon_callback() periodically. The
67 //! Interrupt monitor is enabled after calling \ref classb_rtc_setup(). Note that
68 //! \ref CLASSB_INT_MON should be defined. See \ref rtc_driver for more details.
69 //!
70 //! In order to monitor an interrupt, the following steps should be followed:
71 //! -# Register the interrupt in \ref classb_int_identifiers.
72 //! -# The main application registers the interrupt by calling
73 //! \ref classb_intmon_reg_int(). This gives the monitor information on the
74 //! interrupt, for example the expected frequency.
75 //! -# The interrupts that have to be monitored should call \ref classb_intmon_increase()
76 //! on each execution.
77 //! -# The main application requests that the monitor starts checking the interrupt.
78 //! This is done by changing the interrupt state to \c ENABLE with
79 //! \ref classb_intmon_set_state(). The next time the interrupt monitor runs the
80 //! state of the interrupt will be set to \c ON.
81 //! -# If at some point an interrupt should stop being monitored, the main application
82 //! can change the state to \c DISABLE. The interrupt monitor will change
83 //! the state to \c OFF the next time it is executed.
84 //!
85 //! The fact that the main application has to request to start monitoring an
86 //! interrupt (and that it is the monitor sets the \c ON state) ensures that the
87 //! interrupt counter is synchronized with the interrupt monitor, i.e. the interrupt
88 //! counter starts being increased exactly after a period of the interrupt monitor.
89 //!
90 //! Note that the interrupt counter is only increased if the interrupt is \c ON.
91 //! When an interrupt is \c OFF, the counter should be zero and otherwise the error
92 //! flag will be set. Further, enabling an interrupt that is \c ON or disabling an
93 //! interrupt that is \c OFF will call the error handler if \ref CLASSB_STRICT is defined.
94 //!
95 //! The error handler related to this test is CLASSB_ERROR_HANDLER_INTERRUPT().
96 //!
97
98 //! \addtogroup int_monitor
99 //@{
100
101 //! \defgroup int_mon_conf Settings
102 //! \brief Settings for the interrupt monitor
103 //@{
104
105 //! \brief Enumeration of interrupt identifiers.
106 //!
107 //! This enumeration holds the identifiers for the interrupts that should be monitored.
108 //! These identifiers are used in the interrupt when calling functions related to the
109 //! interrupt monitor: \ref classb_intmon_reg_int(), \ref classb_intmon_increase() and
110 //! \ref classb_intmon_set_state(). Interrupt identifiers are included before
111 //! \ref N_INTERRUPTS, so that it will hold the total number of registered interrupts.
112 enum classb_int_identifiers { MY_INTERRUPT, //!< Identifier of the interrupt
113 N_INTERRUPTS //!< This will keep the number of registered interrupts
114 };
115
116 //! \brief Behavior for re-enabling or re-disabling monitoring of interrupts.
117 //!
118 //! If this is defined, enabling an interrupt that is on \c ON state or disabling
119 //! an interrupt that is on \c OFF state will call the error handler.
120 #define CLASSB_STRICT
121
122 //@}
123
124 //! \defgroup int_mon_def Interrupt data interface
125 //! \brief Definition of data structures used by the monitor.
126 //@{
127
128 /*! \brief Enumeration of interrupt states.
129 *
130 */
131 enum classb_int_states {ON, //!< \internal Interrupt is being monitored (should only be set by the interrupt monitor).
132 OFF, //!< \internal Interrupt is not being monitored (should only be set by the interrupt monitor).
133 ENABLE, //!< Interrupt should start being monitored (can be set by the user application).
134 DISABLE //!< Interrupt should stop being monitored (can be set by the user application).
135 };
136
137 /*!
138 * \internal \brief Data structure for the interrupts that are monitored.
139 *
140 * The main application has to register the interrupt by calling \ref classb_intmon_reg_int().
141 * It is that function that sets the values of the structure.
142 */
143 struct intmon_interrupt {
144 //! \brief Expected number of interrupts in the monitor period.
145 //!
146 //! The monitor period is defined by \ref CLASSB_RTC_INT_PERIOD and \ref CLASSB_RTC_FREQ.
147 uint16_t n;
148 //! \brief Interrupt counter.
149 //!
150 //! This holds the number of interrupt occurrences in the current monitor period.
151 uint16_t c;
152
153 //! \brief Limit for deviation in the counter.
154 //!
155 //! Limit for deviation in the counter.
156 uint16_t l;
157
158 //! \brief State of the interrupt
159 //!
160 //! State of the interrupt
161 enum classb_int_states s;
162 };
163
164 //@}
165
166
167 //! \defgroup int_mon_func Functions
168 //! \brief Functions related to the interrupt monitor
169 //@{
170 void classb_intmon_set_state( enum classb_int_identifiers identifier, enum classb_int_states state);
171 void classb_intmon_reg_int(enum classb_int_identifiers identifier, uint16_t interrupt_counter, uint8_t tolerance_percent) ;
172 void classb_intmon_increase( enum classb_int_identifiers identifier );
173 void classb_intmon_callback( void );
174 //@}
175
176
177 //@}
178
179
180 #endif /* CLASSB_INTERRUPT_MONITOR_H_ */