CRC driver interface.
The CRC driver interface provides device independent APIs, data types, and macros. The CRC header file should be included in an application as follows:
The Cyclic Redundancy Check (CRC) driver is a generic driver that supports calculating a variety of standard CRC codes on blocks of input data.
To calculate the CRC of a block of available data, an application should call:
If the data is only available in noncontiguous memory or is being made available in blocks (e.g. over UART) then the addData and finalise methods may be used to calculate the CRC of individual blocks.
The CRC driver only accepts data lengths that are a multiple of the CRC size. If asked to CRC 7 bytes with a 4-byte CRC, it will throw an error. Similarly, if padding bytes are required for a particular application this must be handled by the caller.
More details on usage are provided in the following sections.
After initializing the CRC driver by calling CRC_init(), the application can open a CRC instance by calling CRC_open(). This function takes an index into the CRC_config[] array, and a CRC parameters data structure. The CRC instance is specified by the index of the CRC in CRC_config[]. Only one CRC index can be used at a time; calling CRC_open() a second time with the same index previously passed to CRC_open() will result in an error. You can, though, re-use the index if the instance is closed via CRC_close().
If no CRC_Params structure is passed to CRC_open(), default values are used. If the open call is successful, it returns a non-NULL value.
An 8-bit CRC with no data processing options. Note that the default POLLING mode uses the CPU to move data so will not allow the device to enter standby in low-power applications.
A 32-bit CRC with data processing options, in BLOCKING mode.
It may be desirable to use the CRC to calculate over blocks of data that are available at different times or non-contiguous in memory. A block-by-block API is available to do this. The following code calculates the CRC of two separate arrays as though they were concatenated.
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
Go to the source code of this file.
Data Structures | |
struct | CRC_Config |
CRC Global configuration. More... | |
struct | CRC_Params |
Struct containing the parameters required for calculating the CRC of a data block. Default values can be set with CRC_Params_init. More... | |
Macros | |
#define | CRC_STATUS_RESERVED (-32) |
#define | CRC_STATUS_SUCCESS (0) |
#define | CRC_STATUS_ERROR (-1) |
#define | CRC_STATUS_RESOURCE_UNAVAILABLE (-2) |
#define | CRC_STATUS_OPERATION_NOT_SUPPORTED (-3) |
#define | CRC_STATUS_LEFTOVER_BYTES_PRESENT (-4) |
Typedefs | |
typedef CRC_Config * | CRC_Handle |
A handle that is returned from an CRC_open() call. More... | |
typedef void(* | CRC_CallbackFxn) (CRC_Handle handle, int_fast16_t status, void *result) |
The definition of a callback function used by the CRC driver when used in CALLBACK mode. More... | |
Enumerations | |
enum | CRC_ReturnBehavior { CRC_RETURN_BEHAVIOR_CALLBACK = 1, CRC_RETURN_BEHAVIOR_BLOCKING = 2, CRC_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which CRC function calls return after completing. More... | |
enum | CRC_Polynomial { CRC_POLYNOMIAL_CRC_8_CCITT, CRC_POLYNOMIAL_CRC_16_CCITT, CRC_POLYNOMIAL_CRC_16_IBM, CRC_POLYNOMIAL_CRC_32_IEEE, CRC_POLYNOMIAL_CRC_32C, CRC_POLYNOMIAL_CRC_32_IO_LINK, CRC_POLYNOMIAL_CRC_TCP, CRC_POLYNOMIAL_CUSTOM_PROGRAMMABLE } |
enum | CRC_ByteSwap { CRC_BYTESWAP_UNCHANGED, CRC_BYTESWAP_HALF_WORDS, CRC_BYTESWAP_BYTES_IN_HALF_WORDS, CRC_BYTESWAP_BYTES_AND_HALF_WORDS } |
These byte swapping configurations are primarily for dealing with endianness mismatch. Not all implementations support all configurations. More... | |
enum | CRC_DataSize { CRC_DATA_SIZE_8BIT, CRC_DATA_SIZE_16BIT, CRC_DATA_SIZE_32BIT } |
The CRC driver will consume data in blocks of this size. Not all implementations support all sizes. More... | |
Functions | |
void | CRC_init (void) |
This function initializes the CRC module. More... | |
void | CRC_Params_init (CRC_Params *params) |
Function to initialize the CRC_Params struct to its defaults. More... | |
CRC_Handle | CRC_open (uint_least8_t index, const CRC_Params *params) |
This function opens a given CRC peripheral. More... | |
int_fast16_t | CRC_calculateFull (CRC_Handle handle, const void *source, size_t sourceBytes, void *result) |
Performs the CRC of the provided bytes, placing the final CRC into result. Waits for HW access. More... | |
int_fast16_t | CRC_addData (CRC_Handle handle, const void *source, size_t sourceBytes) |
Performs the CRC of the provided bytes. Waits for HW access. More... | |
void | CRC_finalize (CRC_Handle handle, void *result) |
Completes the CRC calculation and places the final CRC into result. More... | |
void | CRC_reset (CRC_Handle handle) |
Clears any intermediate results such that the next addData call will begin a new CRC. More... | |
void | CRC_close (CRC_Handle handle) |
Function to close a CRC peripheral specified by the CRC handle. More... | |
Variables | |
const CRC_Params | CRC_defaultParams |
Default CRC_Params structure. More... | |
#define CRC_STATUS_RESERVED (-32) |
#define CRC_STATUS_SUCCESS (0) |
Operation completed successfully
#define CRC_STATUS_ERROR (-1) |
Returned for incorrect parameters
#define CRC_STATUS_RESOURCE_UNAVAILABLE (-2) |
The handle or HW accelerator is currently busy with another operation
#define CRC_STATUS_OPERATION_NOT_SUPPORTED (-3) |
Returned for polynomial (or programmable polynomial) not supported
#define CRC_STATUS_LEFTOVER_BYTES_PRESENT (-4) |
Returned when the number of bytes passed is not a multiple of the data size
typedef CRC_Config* CRC_Handle |
A handle that is returned from an CRC_open() call.
typedef void(* CRC_CallbackFxn) (CRC_Handle handle, int_fast16_t status, void *result) |
The definition of a callback function used by the CRC driver when used in CALLBACK mode.
handle | Handle of the client that started the CRC operation. |
status | Contains the CRC status code from the operation. |
result | Contains the 8/16/32-bit result of the CRC operation. The rest of the word (if unused) will contain zeroes. |
enum CRC_ReturnBehavior |
The way in which CRC function calls return after completing.
This setting controls the return behavior of CRC_calculateFull and CRC_addData. These functions have restrictions on the context from which they may be called (see below). All other functions return immediately.
Task | Hwi | Swi | |
---|---|---|---|
CRC_RETURN_BEHAVIOR_CALLBACK | X | X | X |
CRC_RETURN_BEHAVIOR_BLOCKING | X | ||
CRC_RETURN_BEHAVIOR_POLLING | X | X | X |
enum CRC_Polynomial |
enum CRC_ByteSwap |
These byte swapping configurations are primarily for dealing with endianness mismatch. Not all implementations support all configurations.
Specific configurations are only permitted for sufficiently wide data sizes:
Enumerator | |
---|---|
CRC_BYTESWAP_UNCHANGED | |
CRC_BYTESWAP_HALF_WORDS | |
CRC_BYTESWAP_BYTES_IN_HALF_WORDS | |
CRC_BYTESWAP_BYTES_AND_HALF_WORDS |
enum CRC_DataSize |
void CRC_init | ( | void | ) |
This function initializes the CRC module.
void CRC_Params_init | ( | CRC_Params * | params | ) |
Function to initialize the CRC_Params struct to its defaults.
params | An pointer to CRC_Params structure for initialization |
Defaults values are: returnBehavior = CRC_RETURN_BEHAVIOR_POLLING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
seed = 0xFFFFFFFF, polynomial = CRC_POLYNOMIAL_CRC_8_CCITT, programmablePoly = 0, programmablePolyOrder = 0,
dataSize = CRC_DATA_SIZE_8BIT, finalXorValue = 0, byteSwapInput = CRC_BYTESWAP_UNCHANGED, reverseInputBits = false, invertOutputBits = false, reverseOutputBits = false,
CRC_Handle CRC_open | ( | uint_least8_t | index, |
const CRC_Params * | params | ||
) |
This function opens a given CRC peripheral.
index | Logical peripheral number for the CRC indexed into the CRC_config table |
params | Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only). |
int_fast16_t CRC_calculateFull | ( | CRC_Handle | handle, |
const void * | source, | ||
size_t | sourceBytes, | ||
void * | result | ||
) |
Performs the CRC of the provided bytes, placing the final CRC into result. Waits for HW access.
[in] | handle | A CRC handle returned from CRC_open() |
[in] | source | A pointer to a data source array. |
[in] | sourceBytes | The length of the source array in bytes. |
[out] | result | A pointer to a memory location for the result. Should be at least the width of the data size. |
int_fast16_t CRC_addData | ( | CRC_Handle | handle, |
const void * | source, | ||
size_t | sourceBytes | ||
) |
Performs the CRC of the provided bytes. Waits for HW access.
[in] | handle | A CRC handle returned from CRC_open() |
[in] | source | A pointer to a data source array. |
[in] | sourceBytes | The length of the source array in bytes. |
void CRC_finalize | ( | CRC_Handle | handle, |
void * | result | ||
) |
Completes the CRC calculation and places the final CRC into result.
[in] | handle | A CRC handle returned from CRC_open() |
[out] | result | A pointer to a memory location containing the result. |
void CRC_reset | ( | CRC_Handle | handle | ) |
Clears any intermediate results such that the next addData call will begin a new CRC.
[in] | handle | A CRC handle returned from CRC_open() |
void CRC_close | ( | CRC_Handle | handle | ) |
Function to close a CRC peripheral specified by the CRC handle.
handle | A CRC handle returned from CRC_open() |
const CRC_Params CRC_defaultParams |
Default CRC_Params structure.