MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
DCP: Data Co-Processor

Overview

The MCUXpresso SDK provides a peripheral driver for the Data Co-Processor (DCP) module. For security purposes, the Data Co-Processor (DCP) provides hardware acceleration for the cryptographic algorithms. The features of DCP are: Encryption Algorithms: AES-128 (ECB and CBC modes), Hashing Algorithms: SHA-1 and SHA-256, modified CRC-32, Key selection from the SNVS, DCP internal key storage, or general memory, Internal Memory for storing up to four AES-128 keys-when a key is written to a key slot it can be read only by the DCP AES-128 engine, IP slave interface, and DMA.

The driver comprises two sets of API functions.

In the first set, blocking APIs are provided, for selected subset of operations supported by DCP hardware. The DCP operations are complete (and results are made available for further usage) when a function returns. When called, these functions do not return until a DCP operation is complete. These functions use main CPU for simple polling loops to determine operation complete or error status.

The DCP work packets (descriptors) are placed on the system stack during the blocking API calls. The driver uses critical section (implemented as global interrupt enable/disable) for a short time whenever it needs to pass DCP work packets to DCP channel for processing. Therefore, the driver functions are designed to be re-entrant and as a consequence, one CPU thread can call one blocking API, such as AES Encrypt, while other CPU thread can call another blocking API, such as SHA-256 Update. The blocking functions provide typical interface to upper layer or application software.

In the second set, non-blocking variants of the first set APIs are provided. Internally, the blocking APIs are implemented as a non-blocking operation start, followed by a blocking wait (CPU polling DCP work packet's status word) for an operation completion. The non-blocking functions allow upper layer to inject an application specific operation after the DCP operation start and DCP channel complete events. RTOS event wait and RTOS event set can be an example of such an operation.

DCP Driver Initialization and Configuration

Initialize DCP after Power On Reset or reset cycle Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/dcp

The DCP Driver is initialized by calling the DCP_Init() function. It enables the DCP module clock and configures DCP for operation.

Key Management

The DCP implements four different key storage mechanisms: OTP-key, OTP-Unique key, Payload key, and SRAM-based keys that can be used by the software to securely store keys on a semi-permanent basis (kDCP_KeySlot0 ~ kDCP_KeySlot3). Once the function DCP_AES_SetKey() is called, it sets the AES key for encryption/decryption with the dcp_handle_t structure. In case the SRAM-based key is selected, the function copies and holds the key in memory. In case the OTP key is used, please make sure to set DCP related IOMUXC_GPRs before DCP initialization, since the software reset of DCP must be issued to take these setting in effect. Refer to the DCP_OTPKeySelect() function in BEE driver example.

Comments about API usage in RTOS

DCP transactional (encryption or hash) APIs can be called from multiple threads.

Comments about API usage in interrupt handler

Assuming the host processor receiving interrupt has the ownership of the DCP module, it can request Encrypt/Decrypt/Hash/public_key operations in an interrupt routine. Additionally, as the DCP accesses system memory for it's operation with data (such as message, plaintext, ciphertext, or keys) all data should remain valid until the DCP operation completes.

DCP Driver Examples

Simple examples

Encrypt plaintext by AES engine Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/DCP

Compute hash (CRC-32) The CRC-32 algorithm implements a 32-bit CRC algorithm similar to the one used by Ethernet and many other protocols. The CRC differs from the Unix cksum() function in these four ways: The CRC initial value is 0xFFFFFFFF instead of 0x00000000, final XOR value is 0x00000000 instead of 0xFFFFFFFF, the logic pads the zeros to a 32-bit boundary for the trailing bytes, and it does not post-pend the file length. Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/DCP

Compute hash (SHA-256) Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/DCP

Modules

 DCP AES blocking driver
 
 DCP AES non-blocking driver
 
 DCP HASH driver
 

Data Structures

struct  dcp_work_packet_t
 DCP's work packet. More...
 
struct  dcp_handle_t
 Specify DCP's key resource and DCP channel. More...
 
struct  dcp_context_t
 DCP's context buffer, used by DCP for context switching between channels. More...
 
struct  dcp_config_t
 DCP's configuration structure. More...
 

Enumerations

enum  _dcp_status { kStatus_DCP_Again = MAKE_STATUS(kStatusGroup_DCP, 0) }
 DCP status return codes. More...
 
enum  _dcp_ch_enable_t {
  kDCP_chDisable = 0U,
  kDCP_ch0Enable = 1U,
  kDCP_ch1Enable = 2U,
  kDCP_ch2Enable = 4U,
  kDCP_ch3Enable = 8U,
  kDCP_chEnableAll = 15U
}
 DCP channel enable. More...
 
enum  _dcp_ch_int_enable_t {
  kDCP_chIntDisable = 0U,
  kDCP_ch0IntEnable = 1U,
  kDCP_ch1IntEnable = 2U,
  kDCP_ch2IntEnable = 4U,
  kDCP_ch3IntEnable = 8U
}
 DCP interrupt enable. More...
 
enum  dcp_channel_t {
  kDCP_Channel0 = (1u << 16),
  kDCP_Channel1 = (1u << 17),
  kDCP_Channel2 = (1u << 18),
  kDCP_Channel3 = (1u << 19)
}
 DCP channel selection. More...
 
enum  dcp_key_slot_t {
  kDCP_KeySlot0 = 0U,
  kDCP_KeySlot1 = 1U,
  kDCP_KeySlot2 = 2U,
  kDCP_KeySlot3 = 3U,
  kDCP_OtpKey = 4U,
  kDCP_OtpUniqueKey = 5U,
  kDCP_PayloadKey = 6U
}
 DCP key slot selection. More...
 
enum  dcp_swap_t
 DCP key, input & output swap options. More...
 

Functions

void DCP_Init (DCP_Type *base, const dcp_config_t *config)
 Enables clock to and enables DCP. More...
 
void DCP_Deinit (DCP_Type *base)
 Disable DCP clock. More...
 
void DCP_GetDefaultConfig (dcp_config_t *config)
 Gets the default configuration structure. More...
 
status_t DCP_WaitForChannelComplete (DCP_Type *base, dcp_handle_t *handle)
 Poll and wait on DCP channel. More...
 

Driver version

#define FSL_DCP_DRIVER_VERSION   (MAKE_VERSION(2, 1, 5))
 DCP driver version. More...
 

Data Structure Documentation

struct dcp_work_packet_t
struct dcp_handle_t

Data Fields

dcp_channel_t channel
 Specify DCP channel. More...
 
dcp_key_slot_t keySlot
 For operations with key (such as AES encryption/decryption), specify DCP key slot. More...
 
uint32_t swapConfig
 For configuration of key, input, output byte/word swap options.
 

Field Documentation

dcp_channel_t dcp_handle_t::channel
dcp_key_slot_t dcp_handle_t::keySlot
struct dcp_context_t
struct dcp_config_t

Data Fields

bool gatherResidualWrites
 Enable the ragged writes to the unaligned buffers. More...
 
bool enableContextCaching
 Enable the caching of contexts between the operations. More...
 
bool enableContextSwitching
 Enable automatic context switching for the channels. More...
 
uint8_t enableChannel
 DCP channel enable. More...
 
uint8_t enableChannelInterrupt
 Per-channel interrupt enable. More...
 

Field Documentation

bool dcp_config_t::gatherResidualWrites
bool dcp_config_t::enableContextCaching
bool dcp_config_t::enableContextSwitching
uint8_t dcp_config_t::enableChannel
uint8_t dcp_config_t::enableChannelInterrupt

Macro Definition Documentation

#define FSL_DCP_DRIVER_VERSION   (MAKE_VERSION(2, 1, 5))

Version 2.1.5.

Current version: 2.1.5

Change log:

  • Version 2.1.5
    • Improvements
      • Add support for DCACHE.
  • Version 2.1.4
    • Bug Fix
      • Fix CRC-32 computation issue on the code's block boundary size.
  • Version 2.1.3
    • Bug Fix
      • MISRA C-2012 issue fixed: rule 10.1, 10.3, 10.4, 11.9, 14.4, 16.4 and 17.7.
  • Version 2.1.2
    • Fix sign-compare warning in dcp_reverse_and_copy.
  • Version 2.1.1
    • Add DCP status clearing when channel operation is complete
  • 2.1.0
    • Add byte/word swap feature for key, input and output data
  • Version 2.0.0
    • Initial version

Enumeration Type Documentation

Enumerator
kStatus_DCP_Again 

Non-blocking function shall be called again.

Enumerator
kDCP_chDisable 

DCP channel disable.

kDCP_ch0Enable 

DCP channel 0 enable.

kDCP_ch1Enable 

DCP channel 1 enable.

kDCP_ch2Enable 

DCP channel 2 enable.

kDCP_ch3Enable 

DCP channel 3 enable.

kDCP_chEnableAll 

DCP channel enable all.

Enumerator
kDCP_chIntDisable 

DCP interrupts disable.

kDCP_ch0IntEnable 

DCP channel 0 interrupt enable.

kDCP_ch1IntEnable 

DCP channel 1 interrupt enable.

kDCP_ch2IntEnable 

DCP channel 2 interrupt enable.

kDCP_ch3IntEnable 

DCP channel 3 interrupt enable.

Enumerator
kDCP_Channel0 

DCP channel 0.

kDCP_Channel1 

DCP channel 1.

kDCP_Channel2 

DCP channel 2.

kDCP_Channel3 

DCP channel 3.

Enumerator
kDCP_KeySlot0 

DCP key slot 0.

kDCP_KeySlot1 

DCP key slot 1.

kDCP_KeySlot2 

DCP key slot 2.

kDCP_KeySlot3 

DCP key slot 3.

kDCP_OtpKey 

DCP OTP key.

kDCP_OtpUniqueKey 

DCP unique OTP key.

kDCP_PayloadKey 

DCP payload key.

enum dcp_swap_t

Function Documentation

void DCP_Init ( DCP_Type *  base,
const dcp_config_t config 
)

Enable DCP clock and configure DCP.

Parameters
baseDCP base address
configPointer to configuration structure.
void DCP_Deinit ( DCP_Type *  base)

Reset DCP and Disable DCP clock.

Parameters
baseDCP base address
void DCP_GetDefaultConfig ( dcp_config_t config)

This function initializes the DCP configuration structure to a default value. The default values are as follows. dcpConfig->gatherResidualWrites = true; dcpConfig->enableContextCaching = true; dcpConfig->enableContextSwitching = true; dcpConfig->enableChannnel = kDCP_chEnableAll; dcpConfig->enableChannelInterrupt = kDCP_chIntDisable;

Parameters
[out]configPointer to configuration structure.
status_t DCP_WaitForChannelComplete ( DCP_Type *  base,
dcp_handle_t handle 
)

Polls the specified DCP channel until current it completes activity.

Parameters
baseDCP peripheral base address.
handleSpecifies DCP channel.
Returns
kStatus_Success When data processing completes without error.
kStatus_Fail When error occurs.