Thomas Lyp / DevLibMemoryController

Initial commit

Dependencies:   FastPWM

mbed-dev-master/hal/crc_api.h@0:bb348c97df44, 2020-09-16 (annotated)

Committer:
lypinator
Date:
Wed Sep 16 01:11:49 2020 +0000
Revision:
0:bb348c97df44
Added PWM

Who changed what in which revision?

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