Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
crc_api.h
00001 /** \addtogroup hal */ 00002 /** @{*/ 00003 /* mbed Microcontroller Library 00004 * Copyright (c) 2018 ARM Limited 00005 * 00006 * Licensed under the Apache License, Version 2.0 (the "License"); 00007 * you may not use this file except in compliance with the License. 00008 * You may obtain a copy of the License at 00009 * 00010 * http://www.apache.org/licenses/LICENSE-2.0 00011 * 00012 * Unless required by applicable law or agreed to in writing, software 00013 * distributed under the License is distributed on an "AS IS" BASIS, 00014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00015 * See the License for the specific language governing permissions and 00016 * limitations under the License. 00017 */ 00018 #ifndef MBED_CRC_HAL_API_H 00019 #define MBED_CRC_HAL_API_H 00020 00021 #include <stdbool.h> 00022 #include <stddef.h> 00023 #include <stdint.h> 00024 00025 /** CRC Polynomial value 00026 * 00027 * Different polynomial values supported 00028 */ 00029 typedef enum crc_polynomial { 00030 POLY_OTHER = 0, 00031 POLY_8BIT_CCITT = 0x07, // x8+x2+x+1 00032 POLY_7BIT_SD = 0x9, // x7+x3+1; 00033 POLY_16BIT_CCITT = 0x1021, // x16+x12+x5+1 00034 POLY_16BIT_IBM = 0x8005, // x16+x15+x2+1 00035 POLY_32BIT_ANSI = 0x04C11DB7, // x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1 00036 POLY_32BIT_REV_ANSI = 0xEDB88320 00037 } crc_polynomial_t; 00038 00039 typedef struct crc_mbed_config { 00040 /** CRC Polynomial. Example polynomial: 0x21 = 0010_0011 = x^5+x+1 */ 00041 uint32_t polynomial; 00042 /** CRC Bit Width */ 00043 uint32_t width; 00044 /** Initial seed value for the computation. */ 00045 uint32_t initial_xor; 00046 /** Final xor value for the computation. */ 00047 uint32_t final_xor; 00048 /** Reflect bits on input. */ 00049 bool reflect_in; 00050 /** Reflect bits in final result before returning. */ 00051 bool reflect_out; 00052 } crc_mbed_config_t; 00053 00054 #ifdef DEVICE_CRC 00055 00056 #ifdef __cplusplus 00057 extern "C" { 00058 #endif 00059 00060 /** 00061 * \defgroup hal_crc Hardware CRC 00062 * 00063 * The Hardware CRC HAL API provides a low-level interface to the Hardware CRC 00064 * module of a target platform. 00065 * 00066 * # Defined behaviour 00067 * 00068 * * Function hal_crc_is_supported() returns true if platform supports hardware 00069 * CRC for the given polynomial/width - verified by test ::crc_is_supported_test. 00070 * * Function hal_crc_is_supported() returns false if platform does not support hardware 00071 * CRC for the given polynomial/width - verified by test ::crc_is_supported_test. 00072 * * Function hal_crc_is_supported() returns false if given pointer to configuration 00073 * structure is undefined (NULL) - verified by test ::crc_is_supported_invalid_param_test. 00074 * * If CRC module does not support one of the following settings: initial_xor, final_xor 00075 * reflect_in, reflect_out, then these operations should be handled by the driver 00076 * - Verified by test ::crc_calc_single_test. 00077 * * Platform which supports hardware CRC must be able to handle at least one of the predefined 00078 * polynomial/width configurations that can be constructed in the MbedCRC class: POLY_8BIT_CCITT, 00079 * POLY_7BIT_SD, POLY_16BIT_CCITT, POLY_16BIT_IBM, POLY_32BIT_ANSI 00080 * - verified by test ::crc_is_supported_test, ::crc_calc_single_test. 00081 * * Function hal_crc_compute_partial_start() configures CRC module with the given configuration 00082 * - Verified by test ::crc_calc_single_test. 00083 * * Calling hal_crc_compute_partial_start() without finalising the 00084 * CRC calculation overrides the current configuration - Verified by test ::crc_reconfigure_test. 00085 * * Function hal_crc_compute_partial() writes data to the CRC module - verified by test ::crc_calc_single_test. 00086 * * Function hal_crc_compute_partial() can be call multiple times in succession in order to 00087 * provide additional data to CRC module - verified by test ::crc_calc_multi_test. 00088 * * Function hal_crc_compute_partial() does nothing if pointer to buffer is undefined or 00089 * data length is equal to 0 - verified by test ::crc_compute_partial_invalid_param_test. 00090 * * Function hal_crc_get_result() returns the checksum result from the CRC module 00091 * - verified by tests ::crc_calc_single_test, ::crc_calc_multi_test, ::crc_reconfigure_test. 00092 * 00093 * # Undefined behaviour 00094 * 00095 * * Calling hal_crc_compute_partial_start() function with invalid (unsupported) polynomial. 00096 * * Calling hal_crc_compute_partial() or hal_crc_get_result() functions before hal_crc_compute_partial_start(). 00097 * * Calling hal_crc_get_result() function multiple times. 00098 * 00099 * # Non-functional requirements 00100 * 00101 * * CRC configuration provides the following settings: 00102 * * polynomial - CRC Polynomial, 00103 * * width - CRC bit width, 00104 * * initial_xor - seed value for the computation, 00105 * * final_xor - final xor value for the computation, 00106 * * reflect_in - reflect bits on input, 00107 * * reflect_out - reflect bits in final result before returning. 00108 * 00109 * # Potential bugs 00110 * 00111 * @{ 00112 */ 00113 00114 /** 00115 * \defgroup hal_crc_tests crc hal tests 00116 * The crc HAL tests ensure driver conformance to defined behaviour. 00117 * 00118 * To run the crc hal tests use the command: 00119 * 00120 * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-crc* 00121 * 00122 */ 00123 00124 /** Determine if the current platform supports hardware CRC for given polynomial 00125 * 00126 * The purpose of this function is to inform the CRC Platform API whether the 00127 * current platform has a hardware CRC module and that it can support the 00128 * requested polynomial. 00129 * 00130 * Supported polynomials are restricted to the named polynomials that can be 00131 * constructed in the MbedCRC class, POLY_8BIT_CCITT, POLY_7BIT_SD, 00132 * POLY_16BIT_CCITT, POLY_16BIT_IBM and POLY_32BIT_ANSI. 00133 * 00134 * The current platform must support the given polynomials default parameters 00135 * in order to return a true response. These include: reflect in, reflect out, 00136 * initial xor and final xor. For example, POLY_32BIT_ANSI requires an initial 00137 * and final xor of 0xFFFFFFFF, and reflection of both input and output. If any 00138 * of these settings cannot be configured, the polynomial is not supported. 00139 * 00140 * This function is thread safe; it safe to call from multiple contexts if 00141 * required. 00142 * 00143 * \param config Contains CRC configuration parameters for initializing the 00144 * hardware CRC module. For example, polynomial and initial seed 00145 * values. 00146 * 00147 * \return True if running if the polynomial is supported, false if not. 00148 */ 00149 bool hal_crc_is_supported(const crc_mbed_config_t *config); 00150 00151 /** Initialize the hardware CRC module with the given polynomial 00152 * 00153 * After calling this function, the CRC HAL module is ready to receive data 00154 * using the hal_crc_compute_partial() function. The CRC module on the board 00155 * is configured internally with the specified configuration and is ready 00156 * to receive data. 00157 * 00158 * The platform configures itself based on the default configuration 00159 * parameters of the input polynomial. 00160 * 00161 * This function must be called before calling hal_crc_compute_partial(). 00162 * 00163 * This function must be called with a valid polynomial supported by the 00164 * platform. The polynomial must be checked for support using the 00165 * hal_crc_is_supported() function. 00166 * 00167 * Calling hal_crc_compute_partial_start() multiple times without finalizing the 00168 * CRC calculation with hal_crc_get_result() overrides the current 00169 * configuration and state, and the intermediate result of the computation is 00170 * lost. 00171 * 00172 * This function is not thread safe. A CRC calculation must not be started from 00173 * two different threads or contexts at the same time; calling this function 00174 * from two different contexts may lead to configurations being overwritten and 00175 * results being lost. 00176 * 00177 * \param config Contains CRC configuration parameters for initializing the 00178 * hardware CRC module. For example, polynomial and initial seed 00179 * values. 00180 */ 00181 void hal_crc_compute_partial_start(const crc_mbed_config_t *config); 00182 00183 /** Writes data to the current CRC module. 00184 * 00185 * Writes input data buffer bytes to the CRC data register. The CRC module 00186 * must interpret the data as an array of bytes. 00187 * 00188 * The final transformations are not applied to the data; the CRC module must 00189 * retain the intermediate result so that additional calls to this function 00190 * can be made, appending the additional data to the calculation. 00191 * 00192 * To obtain the final result of the CRC calculation, hal_crc_get_result() is 00193 * called to apply the final transformations to the data. 00194 * 00195 * If the function is passed an undefined pointer, or the size of the buffer is 00196 * specified to be 0, this function does nothing and returns. 00197 * 00198 * This function can be called multiple times in succession. This can be used 00199 * to calculate the CRC result of streamed data. 00200 * 00201 * This function is not thread safe. There is only one instance of the CRC 00202 * module active at a time. Calling this function from multiple contexts 00203 * appends different data to the same, single instance of the module, which causes an 00204 * erroneous value to be calculated. 00205 * 00206 * \param data Input data stream to be written into the CRC calculation 00207 * \param size Size of the data stream in bytes 00208 */ 00209 void hal_crc_compute_partial(const uint8_t *data, const size_t size); 00210 00211 /* Reads the checksum result from the CRC module. 00212 * 00213 * Reads the final checksum result for the final checksum value. The returned 00214 * value is cast as an unsigned 32-bit integer. The actual size of the returned 00215 * result depends on the polynomial used to configure the CRC module. 00216 * 00217 * Additional transformations that are used in the default configuration of the 00218 * input polynomial are applied to the result before it is returned from this 00219 * function. These transformations include: the final xor being appended to the 00220 * calculation, and the result being reflected if required. 00221 * 00222 * Calling this function multiple times is undefined. The first call to this 00223 * function returns the final result of the CRC calculation. The return 00224 * value on successive calls is undefined because the contents of the register after 00225 * accessing them is platform-specific. 00226 * 00227 * This function is not thread safe. There is only one instance of the CRC 00228 * module active at a time. Calling this function from multiple contexts may 00229 * return incorrect data or affect the current state of the module. 00230 * 00231 * \return The final CRC checksum after the reflections and final calculations 00232 * have been applied. 00233 */ 00234 uint32_t hal_crc_get_result(void); 00235 00236 /**@}*/ 00237 00238 #ifdef __cplusplus 00239 }; 00240 #endif 00241 00242 #endif // DEVICE_CRC 00243 #endif // MBED_CRC_HAL_API_H 00244 00245 /**@}*/
Generated on Tue Aug 9 2022 00:37:04 by
