Add Hardware CRC HAL API specification #6708
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| /** \addtogroup hal */ | ||
| /** @{*/ | ||
| /* mbed Microcontroller Library | ||
| * Copyright (c) 2018 ARM Limited | ||
| * | ||
| * Licensed under the Apache License, Version 2.0 (the "License"); | ||
| * you may not use this file except in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, software | ||
| * distributed under the License is distributed on an "AS IS" BASIS, | ||
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| * See the License for the specific language governing permissions and | ||
| * limitations under the License. | ||
| */ | ||
| #ifndef MBED_CRC_HAL_API_H | ||
| #define MBED_CRC_HAL_API_H | ||
|
|
||
| #include <stdbool.h> | ||
| #include <stddef.h> | ||
| #include <stdint.h> | ||
|
|
||
|
There was a problem hiding this comment. As with other HAL APIs we need some intro (have a look at ticker/rtc/sleep) |
||
| /** CRC Polynomial value | ||
| * | ||
| * Different polynomial values supported | ||
| */ | ||
| typedef enum crc_polynomial { | ||
| POLY_OTHER = 0, | ||
| POLY_8BIT_CCITT = 0x07, // x8+x2+x+1 | ||
|
There was a problem hiding this comment. Why Next definitions also have this issue. There was a problem hiding this comment. Hrm, it's technically correct, but misleading. The top bit is excluded from the polynomial. It's defined with the x^8 here. https://en.wikipedia.org/wiki/Cyclic_redundancy_check#Polynomial_representations_of_cyclic_redundancy_checks |
||
| POLY_7BIT_SD = 0x9, // x7+x3+1; | ||
| POLY_16BIT_CCITT = 0x1021, // x16+x12+x5+1 | ||
| POLY_16BIT_IBM = 0x8005, // x16+x15+x2+1 | ||
| POLY_32BIT_ANSI = 0x04C11DB7, // x32+x26+x23+x22+x16+x12+x11+x10+x8+x7+x5+x4+x2+x+1 | ||
| } crc_polynomial_t; | ||
|
|
||
| typedef struct crc_mbed_config { | ||
| /** CRC Polynomial. Example polynomial: 0x21 = 0010_0011 = x^5+x+1 */ | ||
| uint32_t polynomial; | ||
| /** CRC Bit Width */ | ||
| uint32_t width; | ||
| /** Initial seed value for the computation. */ | ||
| uint32_t initial_xor; | ||
| /** Final xor value for the computation. */ | ||
| uint32_t final_xor; | ||
| /** Reflect bits on input. */ | ||
| bool reflect_in; | ||
| /** Reflect bits in final result before returning. */ | ||
| bool reflect_out; | ||
| } crc_mbed_config_t; | ||
|
|
||
| #ifdef DEVICE_CRC | ||
|
|
||
| #ifdef __cplusplus | ||
| extern "C" { | ||
| #endif | ||
|
|
||
| /** | ||
| * \defgroup hal_crc Hardware CRC | ||
| * | ||
| * The Hardware CRC HAL API provides a low-level interface to the Hardware CRC | ||
| * module of a target platform. | ||
| * | ||
| * @{ | ||
| */ | ||
|
|
||
| /** Determine if the current platform supports hardware CRC for given polynomial | ||
| * | ||
| * The purpose of this function is to inform the CRC Platform API whether the | ||
| * current platform has a hardware CRC module and that it can support the | ||
| * requested polynomial. | ||
| * | ||
| * Supported polynomials are restricted to the named polynomials that can be | ||
| * constructed in the MbedCRC class, POLY_8BIT_CCITT, POLY_7BIT_SD, | ||
| * POLY_16BIT_CCITT, POLY_16BIT_IBM and POLY_32BIT_ANSI. | ||
| * | ||
| * The current platform must support the given polynomials default parameters | ||
| * in order to return a true response. These include: reflect in, reflect out, | ||
| * initial xor and final xor. For example, POLY_32BIT_ANSI requires an initial | ||
| * and final xor of 0xFFFFFFFF, and reflection of both input and output. If any | ||
| * of these settings cannot be configured, the polynomial is not supported. | ||
| * | ||
| * This function is thread safe; it safe to call from multiple contexts if | ||
| * required. | ||
| * | ||
| * \param config Contains CRC configuration parameters for initializing the | ||
| * hardware CRC module. For example, polynomial and initial seed | ||
| * values. | ||
| * | ||
| * \return True if running if the polynomial is supported, false if not. | ||
| */ | ||
| bool hal_crc_is_supported(const crc_mbed_config_t* config); | ||
|
There was a problem hiding this comment. Good to inform here as well, that it is not thread safe. |
||
|
|
||
| /** Initialize the hardware CRC module with the given polynomial | ||
| * | ||
| * After calling this function, the CRC HAL module is ready to receive data | ||
| * using the hal_crc_compute_partial() function. The CRC module on the board | ||
| * is configured internally with the specified configuration and is ready | ||
| * to receive data. | ||
| * | ||
| * The platform configures itself based on the default configuration | ||
| * parameters of the input polynomial. | ||
| * | ||
| * This function must be called before calling hal_crc_compute_partial(). | ||
| * | ||
| * This function must be called with a valid polynomial supported by the | ||
| * platform. The polynomial must be checked for support using the | ||
| * hal_crc_is_supported() function. | ||
| * | ||
| * Calling hal_crc_compute_partial_start() multiple times without finalizing the | ||
| * CRC calculation with hal_crc_get_result() overrides the current | ||
| * configuration and state, and the intermediate result of the computation is | ||
| * lost. | ||
| * | ||
| * This function is not thread safe. A CRC calculation must not be started from | ||
| * two different threads or contexts at the same time; calling this function | ||
| * from two different contexts may lead to configurations being overwritten and | ||
| * results being lost. | ||
| * | ||
| * \param config Contains CRC configuration parameters for initializing the | ||
| * hardware CRC module. For example, polynomial and initial seed | ||
| * values. | ||
| */ | ||
| void hal_crc_compute_partial_start(const crc_mbed_config_t* config); | ||
|
|
||
| /** Writes data to the current CRC module. | ||
| * | ||
| * Writes input data buffer bytes to the CRC data register. The CRC module | ||
| * must interpret the data as an array of bytes. | ||
| * | ||
| * The final transformations are not applied to the data; the CRC module must | ||
| * retain the intermediate result so that additional calls to this function | ||
| * can be made, appending the additional data to the calculation. | ||
| * | ||
| * To obtain the final result of the CRC calculation, hal_crc_get_result() is | ||
| * called to apply the final transformations to the data. | ||
| * | ||
| * If the function is passed an undefined pointer, or the size of the buffer is | ||
| * specified to be 0, this function does nothing and returns. | ||
| * | ||
| * This function can be called multiple times in succession. This can be used | ||
| * to calculate the CRC result of streamed data. | ||
| * | ||
| * This function is not thread safe. There is only one instance of the CRC | ||
| * module active at a time. Calling this function from multiple contexts | ||
| * appends different data to the same, single instance of the module, which causes an | ||
| * erroneous value to be calculated. | ||
| * | ||
| * \param data Input data stream to be written into the CRC calculation | ||
| * \param size Size of the data stream in bytes | ||
| */ | ||
| void hal_crc_compute_partial(const uint8_t *data, const size_t size); | ||
|
There was a problem hiding this comment. We do not get any failures from hardware? I believe return of computation should be non-zero and error codes should be propagated |
||
|
|
||
| /* Reads the checksum result from the CRC module. | ||
| * | ||
| * Reads the final checksum result for the final checksum value. The returned | ||
| * value is cast as an unsigned 32-bit integer. The actual size of the returned | ||
| * result depends on the polynomial used to configure the CRC module. | ||
| * | ||
| * Additional transformations that are used in the default configuration of the | ||
| * input polynomial are applied to the result before it is returned from this | ||
| * function. These transformations include: the final xor being appended to the | ||
| * calculation, and the result being reflected if required. | ||
| * | ||
| * Calling this function multiple times is undefined. The first call to this | ||
| * function returns the final result of the CRC calculation. The return | ||
| * value on successive calls is undefined because the contents of the register after | ||
| * accessing them is platform-specific. | ||
| * | ||
| * This function is not thread safe. There is only one instance of the CRC | ||
| * module active at a time. Calling this function from multiple contexts may | ||
| * return incorrect data or affect the current state of the module. | ||
| * | ||
| * \return The final CRC checksum after the reflections and final calculations | ||
| * have been applied. | ||
| */ | ||
| uint32_t hal_crc_get_result(void); | ||
|
There was a problem hiding this comment. None of the CRC functions are thread safe, please indicate in this API as well |
||
|
|
||
| /**@}*/ | ||
|
|
||
| #ifdef __cplusplus | ||
| }; | ||
| #endif | ||
|
|
||
| #endif // DEVICE_CRC | ||
| #endif // MBED_CRC_HAL_API_H | ||
|
|
||
| /**@}*/ | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that the header file needs to be updated to be consistent with other HAL headers.
Doxygen groups, requirements, undefined behavior, potential bugs sections should be added. Example can be found here:
https://github.com/ARMmbed/mbed-os/blob/feature-hal-spec-ticker/hal/us_ticker_api.h
I have also created some example update with the requirements for testing, which can be found here:
https://github.com/mprse/mbed-os/blob/scartmell-arm_crc_tests/hal/crc_api.h
The requirements were created based on provided function descriptions, so probably they need to be extended.
Please fill free to use this example in order to update the header file.