Mistake on this page?
Report an issue in GitHub or email us
crc_api.h
1 /** \addtogroup hal */
2 /** @{*/
3 /* mbed Microcontroller Library
4  * Copyright (c) 2018 ARM Limited
5  * SPDX-License-Identifier: Apache-2.0
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  */
19 #ifndef MBED_CRC_HAL_API_H
20 #define MBED_CRC_HAL_API_H
21 
22 #include <stdbool.h>
23 #include <stddef.h>
24 #include <stdint.h>
25 
26 /** CRC Polynomial value
27  *
28  * Different polynomial values supported
29  */
30 typedef enum crc_polynomial {
31  POLY_OTHER = 0,
32  POLY_8BIT_CCITT = 0x07, // x8+x2+x+1
33  POLY_7BIT_SD = 0x9, // x7+x3+1;
34  POLY_16BIT_CCITT = 0x1021, // x16+x12+x5+1
35  POLY_16BIT_IBM = 0x8005, // x16+x15+x2+1
36  POLY_32BIT_ANSI = 0x04C11DB7, // x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1
37  POLY_32BIT_REV_ANSI = 0xEDB88320
39 
40 typedef struct crc_mbed_config {
41  /** CRC Polynomial. Example polynomial: 0x21 = 0010_0011 = x^5+x+1 */
42  uint32_t polynomial;
43  /** CRC Bit Width */
44  uint32_t width;
45  /** Initial seed value for the computation. */
46  uint32_t initial_xor;
47  /** Final xor value for the computation. */
48  uint32_t final_xor;
49  /** Reflect bits on input. */
50  bool reflect_in;
51  /** Reflect bits in final result before returning. */
54 
55 #if DEVICE_CRC
56 
57 #ifdef __cplusplus
58 extern "C" {
59 #endif
60 
61 /**
62  * \defgroup hal_crc Hardware CRC
63  *
64  * The Hardware CRC HAL API provides a low-level interface to the Hardware CRC
65  * module of a target platform.
66  *
67  * # Defined behaviour
68  *
69  * * Function hal_crc_is_supported() returns true if platform supports hardware
70  * CRC for the given polynomial/width - verified by test ::crc_is_supported_test.
71  * * Function hal_crc_is_supported() returns false if platform does not support hardware
72  * CRC for the given polynomial/width - verified by test ::crc_is_supported_test.
73  * * Function hal_crc_is_supported() returns false if given pointer to configuration
74  * structure is undefined (NULL) - verified by test ::crc_is_supported_invalid_param_test.
75  * * If CRC module does not support one of the following settings: initial_xor, final_xor
76  * reflect_in, reflect_out, then these operations should be handled by the driver
77  * - Verified by test ::crc_calc_single_test.
78  * * Platform which supports hardware CRC must be able to handle at least one of the predefined
79  * polynomial/width configurations that can be constructed in the MbedCRC class: POLY_8BIT_CCITT,
80  * POLY_7BIT_SD, POLY_16BIT_CCITT, POLY_16BIT_IBM, POLY_32BIT_ANSI
81  * - verified by test ::crc_is_supported_test, ::crc_calc_single_test.
82  * * Function hal_crc_compute_partial_start() configures CRC module with the given configuration
83  * - Verified by test ::crc_calc_single_test.
84  * * Calling hal_crc_compute_partial_start() without finalising the
85  * CRC calculation overrides the current configuration - Verified by test ::crc_reconfigure_test.
86  * * Function hal_crc_compute_partial() writes data to the CRC module - verified by test ::crc_calc_single_test.
87  * * Function hal_crc_compute_partial() can be call multiple times in succession in order to
88  * provide additional data to CRC module - verified by test ::crc_calc_multi_test.
89  * * Function hal_crc_compute_partial() does nothing if pointer to buffer is undefined or
90  * data length is equal to 0 - verified by test ::crc_compute_partial_invalid_param_test.
91  * * Function hal_crc_get_result() returns the checksum result from the CRC module
92  * - verified by tests ::crc_calc_single_test, ::crc_calc_multi_test, ::crc_reconfigure_test.
93  *
94  * # Undefined behaviour
95  *
96  * * Calling hal_crc_compute_partial_start() function with invalid (unsupported) polynomial.
97  * * Calling hal_crc_compute_partial() or hal_crc_get_result() functions before hal_crc_compute_partial_start().
98  * * Calling hal_crc_get_result() function multiple times.
99  *
100  * # Non-functional requirements
101  *
102  * * CRC configuration provides the following settings:
103  * * polynomial - CRC Polynomial,
104  * * width - CRC bit width,
105  * * initial_xor - seed value for the computation,
106  * * final_xor - final xor value for the computation,
107  * * reflect_in - reflect bits on input,
108  * * reflect_out - reflect bits in final result before returning.
109  *
110  * # Potential bugs
111  *
112  * @{
113  */
114 
115 /**
116  * \defgroup hal_crc_tests crc hal tests
117  * The crc HAL tests ensure driver conformance to defined behaviour.
118  *
119  * To run the crc hal tests use the command:
120  *
121  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-crc*
122  *
123  */
124 
125 /** Determine if the current platform supports hardware CRC for given polynomial
126  *
127  * The purpose of this function is to inform the CRC Platform API whether the
128  * current platform has a hardware CRC module and that it can support the
129  * requested polynomial.
130  *
131  * Supported polynomials are restricted to the named polynomials that can be
132  * constructed in the MbedCRC class, POLY_8BIT_CCITT, POLY_7BIT_SD,
133  * POLY_16BIT_CCITT, POLY_16BIT_IBM and POLY_32BIT_ANSI.
134  *
135  * The current platform must support the given polynomials default parameters
136  * in order to return a true response. These include: reflect in, reflect out,
137  * initial xor and final xor. For example, POLY_32BIT_ANSI requires an initial
138  * and final xor of 0xFFFFFFFF, and reflection of both input and output. If any
139  * of these settings cannot be configured, the polynomial is not supported.
140  *
141  * This function is thread safe; it safe to call from multiple contexts if
142  * required.
143  *
144  * \param config Contains CRC configuration parameters for initializing the
145  * hardware CRC module. For example, polynomial and initial seed
146  * values.
147  *
148  * \return True if running if the polynomial is supported, false if not.
149  */
150 bool hal_crc_is_supported(const crc_mbed_config_t *config);
151 
152 /** Initialize the hardware CRC module with the given polynomial
153  *
154  * After calling this function, the CRC HAL module is ready to receive data
155  * using the hal_crc_compute_partial() function. The CRC module on the board
156  * is configured internally with the specified configuration and is ready
157  * to receive data.
158  *
159  * The platform configures itself based on the default configuration
160  * parameters of the input polynomial.
161  *
162  * This function must be called before calling hal_crc_compute_partial().
163  *
164  * This function must be called with a valid polynomial supported by the
165  * platform. The polynomial must be checked for support using the
166  * hal_crc_is_supported() function.
167  *
168  * Calling hal_crc_compute_partial_start() multiple times without finalizing the
169  * CRC calculation with hal_crc_get_result() overrides the current
170  * configuration and state, and the intermediate result of the computation is
171  * lost.
172  *
173  * This function is not thread safe. A CRC calculation must not be started from
174  * two different threads or contexts at the same time; calling this function
175  * from two different contexts may lead to configurations being overwritten and
176  * results being lost.
177  *
178  * \param config Contains CRC configuration parameters for initializing the
179  * hardware CRC module. For example, polynomial and initial seed
180  * values.
181  */
183 
184 /** Writes data to the current CRC module.
185  *
186  * Writes input data buffer bytes to the CRC data register. The CRC module
187  * must interpret the data as an array of bytes.
188  *
189  * The final transformations are not applied to the data; the CRC module must
190  * retain the intermediate result so that additional calls to this function
191  * can be made, appending the additional data to the calculation.
192  *
193  * To obtain the final result of the CRC calculation, hal_crc_get_result() is
194  * called to apply the final transformations to the data.
195  *
196  * If the function is passed an undefined pointer, or the size of the buffer is
197  * specified to be 0, this function does nothing and returns.
198  *
199  * This function can be called multiple times in succession. This can be used
200  * to calculate the CRC result of streamed data.
201  *
202  * This function is not thread safe. There is only one instance of the CRC
203  * module active at a time. Calling this function from multiple contexts
204  * appends different data to the same, single instance of the module, which causes an
205  * erroneous value to be calculated.
206  *
207  * \param data Input data stream to be written into the CRC calculation
208  * \param size Size of the data stream in bytes
209  */
210 void hal_crc_compute_partial(const uint8_t *data, const size_t size);
211 
212 /* Reads the checksum result from the CRC module.
213  *
214  * Reads the final checksum result for the final checksum value. The returned
215  * value is cast as an unsigned 32-bit integer. The actual size of the returned
216  * result depends on the polynomial used to configure the CRC module.
217  *
218  * Additional transformations that are used in the default configuration of the
219  * input polynomial are applied to the result before it is returned from this
220  * function. These transformations include: the final xor being appended to the
221  * calculation, and the result being reflected if required.
222  *
223  * Calling this function multiple times is undefined. The first call to this
224  * function returns the final result of the CRC calculation. The return
225  * value on successive calls is undefined because the contents of the register after
226  * accessing them is platform-specific.
227  *
228  * This function is not thread safe. There is only one instance of the CRC
229  * module active at a time. Calling this function from multiple contexts may
230  * return incorrect data or affect the current state of the module.
231  *
232  * \return The final CRC checksum after the reflections and final calculations
233  * have been applied.
234  */
235 uint32_t hal_crc_get_result(void);
236 
237 /**@}*/
238 
239 #ifdef __cplusplus
240 };
241 #endif
242 
243 #endif // DEVICE_CRC
244 #endif // MBED_CRC_HAL_API_H
245 
246 /**@}*/
enum crc_polynomial crc_polynomial_t
CRC Polynomial value.
uint32_t final_xor
Final xor value for the computation.
Definition: crc_api.h:48
bool hal_crc_is_supported(const crc_mbed_config_t *config)
Determine if the current platform supports hardware CRC for given polynomial.
void hal_crc_compute_partial_start(const crc_mbed_config_t *config)
Initialize the hardware CRC module with the given polynomial.
crc_polynomial
CRC Polynomial value.
Definition: crc_api.h:30
uint32_t width
CRC Bit Width.
Definition: crc_api.h:44
void hal_crc_compute_partial(const uint8_t *data, const size_t size)
Writes data to the current CRC module.
bool reflect_out
Reflect bits in final result before returning.
Definition: crc_api.h:52
uint32_t polynomial
CRC Polynomial.
Definition: crc_api.h:42
bool reflect_in
Reflect bits on input.
Definition: crc_api.h:50
uint32_t initial_xor
Initial seed value for the computation.
Definition: crc_api.h:46
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.