ADuCM302x Device Drivers API Reference Manual  Release 3.1.2.0
CRC Device Driver

Cyclic Redundancy Check (CRC) peripheral driver More...

Modules

 Static Configuration
 

Macros

#define ADI_CRC_MEMORY_SIZE   (32u)
 

Typedefs

typedef struct __ADI_CRC_DEVICE * ADI_CRC_HANDLE
 

Enumerations

enum  ADI_CRC_RESULT {
  ADI_CRC_SUCCESS = 0,
  ADI_CRC_FAILURE,
  ADI_CRC_IN_USE,
  ADI_CRC_INSUFFICIENT_MEMORY,
  ADI_CRC_FN_NOT_SUPPORTED,
  ADI_CRC_FN_NOT_PERMITTED,
  ADI_CRC_BAD_HANDLE,
  ADI_CRC_BAD_DEVICE_NUMBER,
  ADI_CRC_INVALID_DMA_CHANNEL,
  ADI_CRC_INVALID_PARAMETER
}
 

Functions

ADI_CRC_RESULT adi_crc_Open (uint32_t DeviceNum, void *pMemory, uint32_t MemorySize, ADI_CRC_HANDLE *phDevice)
 Opens a CRC device instance. More...
 
ADI_CRC_RESULT adi_crc_Close (ADI_CRC_HANDLE const hDevice)
 Closes CRC device instance opened for use. More...
 
ADI_CRC_RESULT adi_crc_RegisterCallback (ADI_CRC_HANDLE const hDevice, ADI_CALLBACK pfCallback, void *const pCBParam)
 Registers or unregisters a callback with the CRC device. More...
 
ADI_CRC_RESULT adi_crc_SetPolynomialVal (ADI_CRC_HANDLE const hDevice, uint32_t PolynomialVal)
 Sets the 32-bit polynomial for CRC operations. More...
 
ADI_CRC_RESULT adi_crc_Compute (ADI_CRC_HANDLE const hDevice, void *pCrcBuf, uint32_t NumBytes, uint32_t NumBits)
 Submits data buffer for CRC computation. More...
 
ADI_CRC_RESULT adi_crc_IsCrcInProgress (ADI_CRC_HANDLE const hDevice, bool *pbCrcInProgress)
 Gets the current CRC peripheral status. More...
 
ADI_CRC_RESULT adi_crc_GetFinalCrcVal (ADI_CRC_HANDLE const hDevice, uint32_t *pFinalCrcVal)
 Gets the final CRC result computed for a data stream. More...
 
ADI_CRC_RESULT adi_crc_GetCurrentCrcVal (ADI_CRC_HANDLE const hDevice, uint32_t *pCurrentCrcVal)
 Gets the current/intermediate CRC result computed for a data stream. More...
 
ADI_CRC_RESULT adi_crc_SetBitMirroring (ADI_CRC_HANDLE const hDevice, const bool bEnable)
 Set the bit mirroring. This function should be called only when device is idle, i.e. when no data are being processd by the CRC. More...
 
ADI_CRC_RESULT adi_crc_SetByteMirroring (ADI_CRC_HANDLE const hDevice, const bool bEnable)
 Set the byte mirroring. This function should be called only when device is disabled. More...
 
ADI_CRC_RESULT adi_crc_EnableWordSwap (ADI_CRC_HANDLE const hDevice, const bool bEnable)
 To enable/disable the word Swap. This function should be called only when device is disabled. More...
 
ADI_CRC_RESULT adi_crc_SetCrcSeedVal (ADI_CRC_HANDLE const hDevice, uint32_t CrcSeedVal)
 Sets the initial seed value for the CRC operation that is about to take place. More...
 
ADI_CRC_RESULT adi_crc_SetLSBFirst (ADI_CRC_HANDLE const hDevice, const bool bEnable)
 Enable the LSB first. More...
 

Detailed Description

Cyclic Redundancy Check (CRC) peripheral driver

The CRC peripheral is used to perform the Cyclic Redundancy Check (CRC) of the block of data that is presented to the peripheral. The peripheral provides a means to periodically verify the integrity of the system memory and it is based on a CRC32 engine that computes the signature of 32-bit data presented to the hardware engine. CRC operations can be core driven or DMA driven depending on static configuration.

- #ADI_CRC_CFG_ENABLE_DMA_SUPPORT set to 0 defines a core driven CRC driver
- #ADI_CRC_CFG_ENABLE_DMA_SUPPORT set to a non 0 value defines a DMA driven
  CRC driver

Core driven CRC operations

The adi_crc_Compute function executes core driven CRC operations to calculate the CRC on the buffer input with the CRC parameters set in the driver. In this mode, data in the submitted buffer is transmitted to the CRC directly by the core.

Memory DMA driver CRC operations

The adi_crc_Compute function executes DMA driven CRC operations to calculate the CRC on the buffer input with the CRC parameters set in the driver. In this mode, data in the submitted buffer is transmitted to the CRC through DMA transfers.

The software DMA channel reserved for the CRC driver is defined by a macro, ADI_CFG_CRC_SOFTWARE_DMA_CHANNEL_ID, which can take a value between 0 and 7. If this macro is not defined, e.g. in a configuration file, then its value is defaulted to 7: in this case, DMA channel SIP7 is used by the CRC driver and DMA_SIP7_Int_Handler becomes the interrupt used by the DMA when a transfer to the CRC is complete.

Computing CRC

The CRC engine performs a 32-bit CRC operation on the incoming data stream.

Sequence of function calls for Computing CRC :

Note
- The application must include drivers/crc/adi_crc.h to use this driver.
- This driver also requires the DMA driver. The application must include the DMA driver sources to avoid link errors.
- This documentation presented here is API documentation only. The device drive user's guide, located in the Documents folder, explains how to use these APIs in an application.

Macro Definition Documentation

◆ ADI_CRC_MEMORY_SIZE

#define ADI_CRC_MEMORY_SIZE   (32u)

The size of types may vary between building tools (int, char, enumerator, etc.). This impacts the memory size required by a CRC driver. Consequently, ADI_CRC_MEMORY_SIZE is environment dependent. The amount of application supplied memory required to operate a core driven CRC device using a CRC driver built in a generic built environment. Note: Create a new macro definition for your targetted development environment if this generic value was not appropriate in your development environment.

Definition at line 92 of file adi_crc.h.

Referenced by adi_crc_Open().

Typedef Documentation

◆ ADI_CRC_HANDLE

typedef struct __ADI_CRC_DEVICE* ADI_CRC_HANDLE

A device handle used in all API functions to identify a CRC device. This handle is obtained when opening a CRC driver using adi_crc_Open. It stops being valid after closing the CRC driver using adi_crc_Close.

Definition at line 144 of file adi_crc.h.

Enumeration Type Documentation

◆ ADI_CRC_RESULT

CRC driver return codes

Enumerator
ADI_CRC_SUCCESS 

0x00 - Generic success

ADI_CRC_FAILURE 

0x01 - Generic failure

ADI_CRC_IN_USE 

0x02 - Supplied CRC device number is already open and in use

ADI_CRC_INSUFFICIENT_MEMORY 

0x03 - Supplied memory is insufficient to operate the CRC device

ADI_CRC_FN_NOT_SUPPORTED 

0x04 - Function not supported

ADI_CRC_FN_NOT_PERMITTED 

0x05 - Function not permitted at current stage

ADI_CRC_BAD_HANDLE 

0x06 - Bad CRC device handle (can be caused by a CRC device not opened)

ADI_CRC_BAD_DEVICE_NUMBER 

0x07 - There is no CRC device identified by this number

ADI_CRC_INVALID_DMA_CHANNEL 

0x08 - Invalid DMA channel assigned to a CRC driver

ADI_CRC_INVALID_PARAMETER 

0x09 - Invalid parameter used in a CRC function

Definition at line 149 of file adi_crc.h.

Function Documentation

◆ adi_crc_Open()

ADI_CRC_RESULT adi_crc_Open ( uint32_t  DeviceNum,
void *  pMemory,
uint32_t  MemorySize,
ADI_CRC_HANDLE phDevice 
)

Opens a CRC device instance.

Parameters
[in]DeviceNumNumber identifying the CRC Device to open.
[in]pMemoryPointer to a ADI_CRC_MEMORY_SIZE. sized buffer to manage the device instance.
[in]MemorySizeSize of the buffer to which "pMemory" points.
[out]phDevicePointer to a location where CRC device handle to be written.
Returns
Status
Note
For the device memory should be of size ADI_CRC_MEMORY_SIZE.

Definition at line 692 of file adi_crc.c.

◆ adi_crc_Close()

ADI_CRC_RESULT adi_crc_Close ( ADI_CRC_HANDLE const  hDevice)

Closes CRC device instance opened for use.

Parameters
[in]hDeviceHandle to CRC Device instance to close.
Returns
Status

Definition at line 770 of file adi_crc.c.

◆ adi_crc_RegisterCallback()

ADI_CRC_RESULT adi_crc_RegisterCallback ( ADI_CRC_HANDLE const  hDevice,
ADI_CALLBACK  pfCallback,
void *const  pCBParam 
)

Registers or unregisters a callback with the CRC device.

It is not required to register a callback for the operation of the driver. Data compare or DMA error will be notified via the adi_crc_IsCrcInProgress() API. But if an application requires the errors/events to be notified immediately it can register a callback with the driver which will be called to notify errors/events.

When a callback is registered the API adi_crc_IsCrcInProgress() will not return error.

Parameters
[in]hDeviceHandle to CRC device instance to work on
[in]pfCallbackPointer to application callback function. The callback function has the prototype void callback(void *pCBParam, uint32_t nEvent, void *pArg) To unregister a callback pass the the pointer to the callback function as NULL.
[in]pCBParamCallback parameter which will be returned back to the application when the callback function is called.
Returns
Status

Definition at line 1249 of file adi_crc.c.

◆ adi_crc_SetPolynomialVal()

ADI_CRC_RESULT adi_crc_SetPolynomialVal ( ADI_CRC_HANDLE const  hDevice,
uint32_t  PolynomialVal 
)

Sets the 32-bit polynomial for CRC operations.

Parameters
[in]hDeviceHandle to CRC device instance to work on.
[in]PolynomialVal32-bit CRC polynomial to use for CRC operation.
Returns
Status

Definition at line 1021 of file adi_crc.c.

◆ adi_crc_Compute()

ADI_CRC_RESULT adi_crc_Compute ( ADI_CRC_HANDLE const  hDevice,
void *  pCrcBuf,
uint32_t  NumBytes,
uint32_t  NumBits 
)

Submits data buffer for CRC computation.

This API can be used to submit data buffer for CRC computation. If NumBits is in [0..7] then the number of bytes to be processed is NumBytes plus one partial byte containing NumBits bits. If DMA mode of operation is selected, buffer is processed using the specified DMA channel.

Parameters
[in]hDeviceHandle of CRC device
[in]pCrcBufAddress of CRC data buffer
[in]NumBytesNumber of whole bytes in CRC data buffer
[in]NumBitsNumber of bits, 0 to 7, in the last partial byte in CRC data buffer
Returns
Status

Definition at line 1068 of file adi_crc.c.

◆ adi_crc_IsCrcInProgress()

ADI_CRC_RESULT adi_crc_IsCrcInProgress ( ADI_CRC_HANDLE const  hDevice,
bool *  pbCrcInProgress 
)

Gets the current CRC peripheral status.

Parameters
[in]hDeviceHandle to CRC device instance to work on
[in]pbCrcInProgressPointer to location to store the current status of CRC peripheral. 'true' when CRC peripheral is in currently performing a CRC operation.
Returns
Status
Note
This function is valid only when device is operating in DMA mode.

Definition at line 1119 of file adi_crc.c.

◆ adi_crc_GetFinalCrcVal()

ADI_CRC_RESULT adi_crc_GetFinalCrcVal ( ADI_CRC_HANDLE const  hDevice,
uint32_t *  pFinalCrcVal 
)

Gets the final CRC result computed for a data stream.

This API gets the final CRC result computed for a data stream and clears the current and final CRC results register. The CRC Current result register holds the current or intermediate CRC result. Whenever a CRC operation is initiated, the CRC peripheral takes the CRC Current register value as initial seed for CRC computation. This API clears both results register to start a fresh CRC computation. Use the adi_crc_GetCurrentCrcVal() API to get an intermediate CRC result without clearing the results register.

Parameters
[in]hDeviceHandle to CRC device instance to work on
[out]pFinalCrcValPointer to location where the final CRC result of a data stream to be processed will be written.
Returns
Status

Definition at line 1170 of file adi_crc.c.

◆ adi_crc_GetCurrentCrcVal()

ADI_CRC_RESULT adi_crc_GetCurrentCrcVal ( ADI_CRC_HANDLE const  hDevice,
uint32_t *  pCurrentCrcVal 
)

Gets the current/intermediate CRC result computed for a data stream.

Parameters
[in]hDeviceHandle to CRC device instance to work on
[out]pCurrentCrcValPointer to location where the intermediate CRC result of a data stream to be processed will be written.
Returns
Status

Definition at line 1203 of file adi_crc.c.

◆ adi_crc_SetBitMirroring()

ADI_CRC_RESULT adi_crc_SetBitMirroring ( ADI_CRC_HANDLE const  hDevice,
const bool  bEnable 
)

Set the bit mirroring. This function should be called only when device is idle, i.e. when no data are being processd by the CRC.

Parameters
[in]hDeviceDevice handle obtained from adi_crc_Open().
[in]bEnableBoolean flag to enable/disable bit mirroring. true : To Enable bit mirroring. false : To Disable bit mirroring.
Returns
Status
See also
adi_crc_SetByteMirroring().
adi_crc_SetWordSwap().

Definition at line 815 of file adi_crc.c.

◆ adi_crc_SetByteMirroring()

ADI_CRC_RESULT adi_crc_SetByteMirroring ( ADI_CRC_HANDLE const  hDevice,
const bool  bEnable 
)

Set the byte mirroring. This function should be called only when device is disabled.

Parameters
[in]hDeviceDevice handle obtained from adi_crc_Open().
[in]bEnableBoolean flag to enable/disable byte mirroring. true : To Enable byte mirroring. false : To Disable byte mirroring.
Returns
Status
See also
adi_crc_EnableBitMirroring().
adi_crc_EnableWordSwap().

Definition at line 858 of file adi_crc.c.

◆ adi_crc_EnableWordSwap()

ADI_CRC_RESULT adi_crc_EnableWordSwap ( ADI_CRC_HANDLE const  hDevice,
const bool  bEnable 
)

To enable/disable the word Swap. This function should be called only when device is disabled.

Parameters
[in]hDeviceDevice handle obtained from adi_crc_Open().
[in]bEnableBoolean flag to enable/disable word swap. true : To Enable word swap. false : To Disable word swap.
Returns
Status
See also
adi_crc_SetBitMirroring().
adi_crc_SetByteMirroring().

Definition at line 946 of file adi_crc.c.

◆ adi_crc_SetCrcSeedVal()

ADI_CRC_RESULT adi_crc_SetCrcSeedVal ( ADI_CRC_HANDLE const  hDevice,
uint32_t  CrcSeedVal 
)

Sets the initial seed value for the CRC operation that is about to take place.

Parameters
[in]hDeviceHandle to CRC device instance to work on.
[in]CrcSeedValInitial seed value for the CRC operation that is about to take place.
Returns
Status

Definition at line 985 of file adi_crc.c.

◆ adi_crc_SetLSBFirst()

ADI_CRC_RESULT adi_crc_SetLSBFirst ( ADI_CRC_HANDLE const  hDevice,
const bool  bEnable 
)

Enable the LSB first.

Parameters
[in]hDeviceDevice handle obtained from adi_crc_Open().
[in]bEnableBoolean flag which indicate whether LSB first OR MSB first for CRC calculation. true : For LSB First CRC calculation false : For MSB First CRC calculation
Returns
Status
See also
adi_crc_EnableBitmirroring().
adi_crc_EnableWordSwap().

Definition at line 903 of file adi_crc.c.