| 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