Detailed Description

CRC driver interface.

Overview

The CRC driver interface provides device independent APIs, data types, and macros. The CRC header file should be included in an application as follows:

#include <ti/drivers/CRC.h>

The Cyclic Redundancy Check (CRC) driver is a generic driver that supports calculating a variety of standard CRC codes on blocks of input data.

Usage

To calculate the CRC of a block of available data, an application should call:

CRC_init(): Initialize the CRC driver.
CRC_Params_init(): Initialize a default CRC_Params structure.
CRC_open(): Open an instance of the CRC driver, passing the initialized parameters, or NULL, and an index (described later).
CRC_calculateFull(): Calculate the CRC of a data block.
CRC_close(): De-initialize the CRC instance.

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.

Synopsis

CRC_Handle      handle;
CRC_Params      params;
int_fast16_t    status;
uint32_t        result;
uint8_t         source[NUM_BYTES];
CRC_init();  // Initialize the CRC driver
CRC_Params_init(&params);     // Initialize CRC parameters
params.returnBehavior = CRC_RETURN_BEHAVIOR_BLOCKING;
params.polynomial = CRC_POLYNOMIAL_CRC_16_CCITT;
params.dataSize = CRC_DATA_SIZE_32BIT;
params.seed = 0xFFFF;
params.byteSwapInput = CRC_BYTESWAP_UNCHANGED;
handle = CRC_open(CONFIG_CRC0, &params);
if (handle == NULL) {
    while (1);  // CRC_open() failed
}
// Fill in source
status = CRC_calculateFull(handle, source, NUM_BYTES, &result);
if (status != CRC_STATUS_SUCCESS) {
    // Error with parameters, or CRC resource was unavailable
    while (1);
}

More details on usage are provided in the following sections.

Examples

Opening a CRC instance

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.

CRC_Handle handle;
CRC_Params params;
// Initialize the CRC driver
CRC_init();
// Initialize optional CRC parameters for CALLBACK mode
CRC_Params_init(&params);
params.returnBehavior = CRC_RETURN_BEHAVIOR_CALLBACK;
params.callbackFxn = myCallbackFunction;
handle = CRC_open(CONFIG_CRC0, &params);
if (handle == NULL) {
    // CRC_open() failed
    while (1);
}

Using the calculateFull API

CRC-8-CCITT without data processing

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.

CRC_Handle      handle;
int_fast16_t    status;
uint8_t         source[NUM_BYTES];
uint8_t         result;
// Initialize the CRC driver
CRC_init();
// The defaults are set to a POLLING mode 8-bit CRC with seed 0xFF
// We can pass NULL instead of a Params struct to make use of this
handle = CRC_open(CONFIG_CRC0, NULL);
if (handle == NULL) {
    while (1);  // CRC_open() failed
}
status = CRC_calculateFull(handle, source, NUM_BYTES, &result);
if (status != CRC_STATUS_SUCCESS) {
    // Error with parameters, or CRC resource was unavailable
    while (1);
}

CRC-32-IEEE with endianness reversal

A 32-bit CRC with data processing options, in BLOCKING mode.

CRC_Handle      handle;
CRC_Params      params;
int_fast16_t    status;
uint32_t        result;
uint8_t         source[NUM_BYTES];
CRC_init();  // Initialize the CRC driver
CRC_Params_init(&params);     // Initialize CRC parameters
params.returnBehavior = CRC_RETURN_BEHAVIOR_BLOCKING;
params.byteSwapInput = CRC_BYTESWAP_BYTES_AND_HALF_WORDS;
params.polynomial = CRC_POLYNOMIAL_CRC_32_IEEE;
params.dataSize = CRC_DATA_SIZE_32BIT;
params.seed = 0xFFFFFFFF;
handle = CRC_open(CONFIG_CRC0, &params);
if (handle == NULL) {
    while (1);  // CRC_open() failed
}
// Obtain data for the source buffer
status = CRC_calculateFull(handle, source, NUM_BYTES, &result);
if (status != CRC_STATUS_SUCCESS) {
    // Error with parameters, or CRC resource was unavailable
    while (1);
}

Using the addData API

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.

CRC_Handle      handle;
CRC_Params      params;
int_fast16_t    status;
uint32_t        result;
uint32_t         sourceA [NUM_BYTES] = { ... };
uint32_t         sourceB [NUM_BYTES] = { ... };
CRC_init();
CRC_Params_init(&params);
params.byteSwapInput = CRC_BYTESWAP_UNCHANGED;
params.polynomial = CRC_POLYNOMIAL_CRC_32C;
params.dataSize = CRC_DATA_SIZE_32BIT;
params.seed = 0xFFFFFFFF;
handle = CRC_open(CONFIG_CRC0, &params);
if (handle == NULL) {
    while (1);  // CRC_open() failed
}
status = CRC_addData(handle, sourceA, NUM_BYTES);
if (status != CRC_STATUS_SUCCESS) {
    // CRC resource was unavailable
    while (1);
}
status = CRC_addData(handle, sourceB, NUM_BYTES);
if (status != CRC_STATUS_SUCCESS) {
    // CRC resource was unavailable
    while (1);
}
CRC_finalize(handle, &result);

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

Include dependency graph for CRC.h:

This graph shows which files directly or indirectly include this file:

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...

Macro Definition Documentation

§ CRC_STATUS_RESERVED

#define CRC_STATUS_RESERVED (-32)

§ CRC_STATUS_SUCCESS

#define CRC_STATUS_SUCCESS (0)

Operation completed successfully

§ CRC_STATUS_ERROR

#define CRC_STATUS_ERROR (-1)

Returned for incorrect parameters

§ CRC_STATUS_RESOURCE_UNAVAILABLE

#define CRC_STATUS_RESOURCE_UNAVAILABLE (-2)

The handle or HW accelerator is currently busy with another operation

§ CRC_STATUS_OPERATION_NOT_SUPPORTED

#define CRC_STATUS_OPERATION_NOT_SUPPORTED (-3)

Returned for polynomial (or programmable polynomial) not supported

§ CRC_STATUS_LEFTOVER_BYTES_PRESENT

#define CRC_STATUS_LEFTOVER_BYTES_PRESENT (-4)

Returned when the number of bytes passed is not a multiple of the data size

Typedef Documentation

§ CRC_Handle

typedef CRC_Config* CRC_Handle

A handle that is returned from an CRC_open() call.

§ CRC_CallbackFxn

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.

Parameters

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.

Enumeration Type Documentation

§ CRC_ReturnBehavior

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

Enumerator
CRC_RETURN_BEHAVIOR_CALLBACK	The function call will return immediately while the CRC operation goes on in the background. The registered callback function is called after the operation completes. The context the callback function is called (task, HWI, SWI) is implementation-dependent.
CRC_RETURN_BEHAVIOR_BLOCKING	The function call will block while CRC operation goes on in the background. CRC operation results are available after the function returns.
CRC_RETURN_BEHAVIOR_POLLING	The CPU is used to feed data to the CRC. CRC operation results are available after the function returns.

§ CRC_Polynomial

enum CRC_Polynomial

Enumerator
CRC_POLYNOMIAL_CRC_8_CCITT	CRC-8 CCITT: polynomial 0x07
CRC_POLYNOMIAL_CRC_16_CCITT	CRC-16 CCITT: polynomial 0x1021
CRC_POLYNOMIAL_CRC_16_IBM	CRC-16 IBM: polynomial 0x8005
CRC_POLYNOMIAL_CRC_32_IEEE	CRC-32 IEEE/Ethernet: polynomial 0x04C11DB7
CRC_POLYNOMIAL_CRC_32C	CRC-32C Castagnoli: polynomial 0x1EDC6F41
CRC_POLYNOMIAL_CRC_32_IO_LINK	CRC-32 IO-LINK: polynomial 0xF4ACFB13
CRC_POLYNOMIAL_CRC_TCP	The TCP Checksum does not have a traditional polynomial, as it consists of repeated addition rather than typical long division operations.
CRC_POLYNOMIAL_CUSTOM_PROGRAMMABLE	Some implementations support programmable polynomials. In this case, use CUSTOM_PROGRAMMABLE and set the polynomial in the programmablePoly field of the Operation struct.

§ CRC_ByteSwap

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:

32-bit data size: all byte swap configurations are permitted
16-bit data size: only UNCHANGED and BYTES_IN_HALF_WORDS are permitted
8-bit data size: only UNCHANGED is permitted

Enumerator
CRC_BYTESWAP_UNCHANGED
CRC_BYTESWAP_HALF_WORDS
CRC_BYTESWAP_BYTES_IN_HALF_WORDS
CRC_BYTESWAP_BYTES_AND_HALF_WORDS

§ CRC_DataSize

enum CRC_DataSize

The CRC driver will consume data in blocks of this size. Not all implementations support all sizes.

Enumerator
CRC_DATA_SIZE_8BIT
CRC_DATA_SIZE_16BIT
CRC_DATA_SIZE_32BIT

Function Documentation

§ CRC_init()

void CRC_init ( void )

This function initializes the CRC module.

Precondition: The CRC_config structure must exist and be persistent before this function can be called. This function must also be called before any other CRC driver APIs. This function call does not modify any peripheral registers.

§ CRC_Params_init()

void CRC_Params_init ( CRC_Params * params )

Function to initialize the CRC_Params struct to its defaults.

Parameters

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_open()

CRC_Handle CRC_open	(	uint_least8_t	index,
		const CRC_Params *	params
	)

This function opens a given CRC peripheral.

Precondition: CRC controller has been initialized using CRC_init()

Parameters

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

Returns: A CRC_Handle on success or a NULL on an error or if it has been opened already.

See also: CRC_init(); CRC_close()

§ CRC_calculateFull()

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.

Note: The data source array will be accessed in multiples of the data size defined in the operation struct. If padding bytes are required (e.g. to pad a 9-byte message to 12 bytes for 32-bit operation) this must be handled by the application.

Precondition: CRC_open() has to be called first.

Parameters

[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.

Returns: A status code

§ CRC_addData()

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.

Note: The data source array will be accessed in multiples of the data size defined in the operation struct. If padding bytes are required (e.g. to pad a 9-byte message to 12 bytes for 32-bit operation) this must be handled by the application.

Precondition: CRC_open() has to be called first.

Postcondition: CRC_addData to check another data block or CRC_finalize to extract the result. CRC_reset will clear an existing partial result (finalise also does this.)

Parameters

[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.

Returns: A status code

See also: CRC_setup

§ CRC_finalize()

void CRC_finalize	(	CRC_Handle	handle,
		void *	result
	)

Completes the CRC calculation and places the final CRC into result.

Note: The data source array will be accessed in multiples of the data size defined in the operation struct. If padding bytes are required (e.g. to pad a 9-byte message to 12 bytes for 32-bit operation) this must be handled by the application.

Precondition: CRC_open() must be called. CRC_addData should be called at least once.

Parameters

[in]	handle	A CRC handle returned from CRC_open()
[out]	result	A pointer to a memory location containing the result.

See also: CRC_setup; CRC_addData

§ CRC_reset()

void CRC_reset ( CRC_Handle handle )

Clears any intermediate results such that the next addData call will begin a new CRC.

Precondition: CRC_open() must be called. CRC_addData should be called at least once.

Parameters

[in] handle A CRC handle returned from CRC_open()

See also: CRC_setup; CRC_addData

§ CRC_close()

void CRC_close ( CRC_Handle handle )

Function to close a CRC peripheral specified by the CRC handle.

Precondition: CRC_open() has to be called first.

Parameters

handle A CRC handle returned from CRC_open()

See also: CRC_open()

Variable Documentation

§ CRC_defaultParams

const CRC_Params CRC_defaultParams

Default CRC_Params structure.

See also: CRC_Params_init()

Detailed Description

Overview

Usage

Synopsis

Examples

Opening a CRC instance

Using the calculateFull API

CRC-8-CCITT without data processing

CRC-32-IEEE with endianness reversal

Using the addData API

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ CRC_STATUS_RESERVED

§ CRC_STATUS_SUCCESS

§ CRC_STATUS_ERROR

§ CRC_STATUS_RESOURCE_UNAVAILABLE

§ CRC_STATUS_OPERATION_NOT_SUPPORTED

§ CRC_STATUS_LEFTOVER_BYTES_PRESENT

Typedef Documentation

§ CRC_Handle

§ CRC_CallbackFxn

Enumeration Type Documentation

§ CRC_ReturnBehavior

§ CRC_Polynomial

§ CRC_ByteSwap

§ CRC_DataSize

Function Documentation

§ CRC_init()

§ CRC_Params_init()

§ CRC_open()

§ CRC_calculateFull()

§ CRC_addData()

§ CRC_finalize()

§ CRC_reset()

§ CRC_close()

Variable Documentation

§ CRC_defaultParams