 |
MCUXpresso SDK API Reference Manual
Rev. 0
NXP Semiconductors
|
|
MCUXpresso SDK API Reference Manual
Rev. 0
NXP Semiconductors
|
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.
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.
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.
DCP transactional (encryption or hash) APIs can be called from multiple threads.
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.
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... | |
| 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. | |
| 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... | |
| 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 |
| #define FSL_DCP_DRIVER_VERSION (MAKE_VERSION(2, 1, 5)) |
Version 2.1.5.
Current version: 2.1.5
Change log:
| enum _dcp_status |
| enum _dcp_ch_enable_t |
| enum _dcp_ch_int_enable_t |
| enum dcp_channel_t |
| enum dcp_key_slot_t |
| enum dcp_swap_t |
| void DCP_Init | ( | DCP_Type * | base, |
| const dcp_config_t * | config | ||
| ) |
Enable DCP clock and configure DCP.
| base | DCP base address |
| config | Pointer to configuration structure. |
| void DCP_Deinit | ( | DCP_Type * | base | ) |
Reset DCP and Disable DCP clock.
| base | DCP 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;
| [out] | config | Pointer to configuration structure. |
| status_t DCP_WaitForChannelComplete | ( | DCP_Type * | base, |
| dcp_handle_t * | handle | ||
| ) |
Polls the specified DCP channel until current it completes activity.
| base | DCP peripheral base address. |
| handle | Specifies DCP channel. |
