The Hardware CRC HAL API provides a low-level interface to the Hardware CRC module of a target platform. More...

Modules
	crc hal tests
	The crc HAL tests ensure driver conformance to defined behaviour.

Functions
void	hal_crc_compute_partial_start (const crc_mbed_config_t *config)
	Initialize the hardware CRC module with the given polynomial. More...

void	hal_crc_compute_partial (const uint8_t *data, const size_t size)
	Writes data to the current CRC module. More...

Detailed Description

The Hardware CRC HAL API provides a low-level interface to the Hardware CRC module of a target platform.

Defined behaviour

Macro HAL_CRC_IS_SUPPORTED() evaluates true if platform supports hardware CRC for the given polynomial/width - verified by test crc_is_supported_test.
Macro HAL_CRC_IS_SUPPORTED() evaluates false if platform does not support hardware CRC for the given polynomial/width - verified by test crc_is_supported_test.
If CRC module does not support any of the following settings: initial_xor, final_xor reflect_in, reflect_out, then these operations must be handled by the driver
- Verified by test crc_calc_single_test.
Platform which supports hardware CRC must be able to handle at least one of the predefined polynomial/width configurations that can be constructed in the MbedCRC class: POLY_8BIT_CCITT, POLY_7BIT_SD, POLY_16BIT_CCITT, POLY_16BIT_IBM, POLY_32BIT_ANSI
- verified by test crc_is_supported_test, crc_calc_single_test.
Function hal_crc_compute_partial_start() configures CRC module with the given configuration
- Verified by test crc_calc_single_test.
Calling hal_crc_compute_partial_start() without finalising the CRC calculation overrides the current configuration - Verified by test crc_reconfigure_test.
Function hal_crc_compute_partial() writes data to the CRC module - verified by test crc_calc_single_test.
Function hal_crc_compute_partial() can be call multiple times in succession in order to provide additional data to CRC module - verified by test crc_calc_multi_test.
Function hal_crc_compute_partial() does nothing if pointer to buffer is undefined or data length is equal to 0 - verified by test crc_compute_partial_invalid_param_test.
Function hal_crc_get_result() returns the checksum result from the CRC module
- verified by tests crc_calc_single_test, crc_calc_multi_test, crc_reconfigure_test.

Undefined behaviour

Calling hal_crc_compute_partial_start() function with invalid (unsupported) polynomial.
Calling hal_crc_compute_partial() or hal_crc_get_result() functions before hal_crc_compute_partial_start().
Calling hal_crc_get_result() function multiple times.

Non-functional requirements

CRC configuration provides the following settings:
- polynomial - CRC Polynomial,
- width - CRC bit width,
- initial_xor - seed value for the computation,
- final_xor - final xor value for the computation,
- reflect_in - reflect bits on input,
- reflect_out - reflect bits in final result before returning.

Potential bugs

Macros

Platform support for particular CRC polynomials is indicated by the macro HAL_CRC_IS_SUPPORTED(polynomial, width), which must be defined in device.h, or a file included from there.

The macro must evaluate to a constant boolean expression when given constant parameters.

The current platform must support the given polynomial with all possible other config parameters if the macro evaluates to true. These are: reflect in, reflect out, initial xor and final xor. If any of these settings of these settings cannot be configured, the polynomial is not supported.

Example:

#define HAL_CRC_IS_SUPPORTED(polynomial, width) \

((width) == 16 || ((width) == 32 && (polynomial) == POLY_32BIT_ANSI)

Function Documentation

◆ hal_crc_compute_partial_start()

void hal_crc_compute_partial_start ( const crc_mbed_config_t * config )

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() macro.

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.

Parameters

config Contains CRC configuration parameters for initializing the hardware CRC module. For example, polynomial and initial seed values.

◆ hal_crc_compute_partial()

void hal_crc_compute_partial	(	const uint8_t *	data,
		const size_t	size
	)

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.