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