Xmega IEC60730 Class B Library  1.0
 All Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
classb_crc.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 defines used in connection with CRC memory tests.
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 __CRC_H__
53 #define __CRC_H__
54 
55 #include "avr_compiler.h"
56 #include "error_handler.h"
57 
58 /**
59  * \defgroup classb_crc CRC Tests
60  *
61  * \brief This CRC module can be used to check the Flash and EEPROM memories.
62  *
63  * \section crc_intro Introduction to CRC
64  *
65  * A cyclic redundancy check (CRC) is an error detection technique test algorithm
66  * used to detect errors in data. It is commonly used to determine the correctness
67  * of data stored in memory or data that is received through some communication
68  * channel. The CRC algorithm takes a data stream or a block of data as input and
69  * generates a 16- or 32-bit output that can be used as a checksum. We suggest
70  * two possible methods to detect errors using this checksum:
71  *
72  * -Compute checksum of the data section and compare with the previous one.
73  * If they are different, there is an error.
74  *
75  * -Compute checksum of the extended data section (data section and original checksum).
76  * The resulting checksum should be a fixed implementation-specific value,
77  * otherwise there is an error.
78  *
79  * If there were errors in the data, the application should take corrective actions,
80  * e.g. requesting the data to be sent again or simply not using the incorrect data.
81  *
82  * The CRC Tests module implements 16-bit CCITT CRC and IEE802.3 32-bit CRC algorithms
83  * in software and hardware.
84  * - \ref classb_crc_sw
85  * - \ref classb_crc_hw
86  *
87  * \section crc_usage Usage
88  *
89  * There are a number of symbols in \ref crc_conf that can be defined or undefined
90  * in order to choose between software and hardware implementations, and 16-bit and
91  * 32-bit CRC. The software implementation can be further configured in the
92  * corresponding header file. To calculate an EEPROM checksum, use the functions
93  * - \c CLASSB_CRC[16/32]_EEPROM_[SW/HW]
94  *
95  * To calculate a Flash checksum, use the functions
96  * - \c CLASSB_CRC[16/32]_Flash_[SW/HW].
97  *
98  * If there should be any error, the error handler \ref CLASSB_ERROR_HANDLER_CRC() would
99  * be called.
100  *
101  * \note Interrupts must be disabled during this test.
102  *
103  * \section crc_speed Execution speed
104  *
105  * We provide an estimate for the execution speed of different CRC implementations. Note that this is
106  * based on empirical results.
107  * - EEPROM
108  * - CRC32 lookup table is ~45% slower than HW.
109  * - CRC32 direct calculation is ~750% slower than HW.
110  * - CRC16 lookup table is ~20% slower than HW.
111  * - CRC16 direct calculation is ~430% slower than HW.
112  * - Flash
113  * - CRC32 lookup table is ~4600% slower than HW.
114  * - CRC32 direct calculation is ~15800% slower than HW.
115  * - CRC16 lookup table is ~3% slower than HW.
116  * - CRC16 direct calculation is ~275% slower than HW.
117  */
118 
119 
120 //! \addtogroup classb_crc
121 //@{
122 
123 
124 
125 //! \defgroup crc_conf Configuration of CRC Implementation
126 //!
127 //! \brief Symbols that can be defined to configure the CRC computation.
128 //!
129 //! This is used to avoid compiling code that will not be used.
130 //@{
131 //! \brief Compile hardware implementation
132 #define CLASSB_CRC_USE_HW
133 //! \brief Compile software implementation
134 #define CLASSB_CRC_USE_SW
135 //! \brief Compile 16-bit functions
136 #define CLASSB_CRC_16_BIT
137 //! \brief Compile 32-bit functions
138 #define CLASSB_CRC_32_BIT
139 //@}
140 
141 
142 //! \internal \defgroup crc_int_conf CRC settings that should not be modified
143 //!
144 //! \brief This options make sure that the CRC computation complies with
145 //! the standard 16-bit CCITT CRC and IEE802.3 32-bit CRC.
146 //@{
147 //! \internal \brief Initial remainder for the 16-bit CRC
148 #define CRC16_INITIAL_REMAINDER 0x0000
149 //! \internal \brief Initial remainder for the 32-bit CRC
150 #define CRC32_INITIAL_REMAINDER 0xFFFFFFFF
151 //@}
152 
153 
154 //! \defgroup crc_types Type definitions for CRC functions
155 //!
156 //! \brief Data types used in connection with CRC computations.
157 //!
158 //! This includes the type for variables that stores the data size in bytes,
159 //! memory addresses in Flash, and pointers to memory. Both for Flash and EEPROM
160 //! there are void pointer types and pointers to byte. Variables can be assigned
161 //! a memory attribute with IAR. Therefore, pointers will be large enough to hold
162 //! the address of a given variable. However, with GCC pointers have 16 bits. This
163 //! means that if a device has a large program memory, we have to use 32-bits
164 //! variables to store Flash addresses.
165 //@{
166 
167 /*! \brief Data type to use for byte counts in CRC computations.
168  * This type should be kept as small as possible to optimize for speed.
169  */
170 typedef uint32_t crcbytenum_t;
171 
172 /*! \brief Data type for holding flash memory addresses.
173  * Depending of the size of the device it will be necessary to use 32 or 16 bits.
174  */
175 #if (PROGMEM_SIZE >= 0x10000UL) || defined(__DOXYGEN__)
176  typedef uint32_t flash_addr_t;
177 #else
178  typedef uint16_t flash_addr_t;
179 #endif
180 
181 // Pointer types for CRC functions, needed for IAR and GCC compatibility.
182 #if defined(__ICCAVR__)
183  typedef const void __eeprom * eepromptr_t;
184  typedef const uint8_t __eeprom * eeprom_uint8ptr_t;
185  typedef const uint16_t __eeprom * eeprom_uint16ptr_t;
186  typedef const uint32_t __eeprom * eeprom_uint32ptr_t;
187  typedef const void _MEMATTR * flashptr_t;
188  typedef const uint8_t _MEMATTR * flash_uint8ptr_t;
189 #elif defined (__GNUC__) || defined (__DOXYGEN__)
190  //! \brief Generic pointer to EEPROM.
191  typedef const void* eepromptr_t;
192  //! \brief Pointer to a byte in EEPROM.
193  typedef const uint8_t* eeprom_uint8ptr_t;
194  //! \brief Pointer to two bytes in EEPROM.
195  typedef const uint16_t * eeprom_uint16ptr_t;
196  //! \brief Pointer to four bytes in EEPROM.
197  typedef const uint32_t * eeprom_uint32ptr_t;
198  //! \brief Generic pointer to Flash.
199  typedef flash_addr_t flashptr_t;
200  //! \brief Pointer to a byte in Flash.
201  typedef flash_addr_t flash_uint8ptr_t;
202 #else
203  #error Unknown compiler!
204 #endif
205 
206 //@}
207 
208 //@}
209 
210 #ifdef CLASSB_CRC_USE_HW
211  #include "classb_crc_hw.h"
212 #endif
213 
214 #ifdef CLASSB_CRC_USE_SW
215  #include "classb_crc_sw.h"
216 #endif
217 
218 #if defined(__GNUC__) && !defined(__OPTIMIZE__)
219 # error Optimization must be enabled to successfully write to protected registers, due to timing constraints.
220 #endif
221 
222 
223 #endif
224