SE - Secure Element
Description
Secure Element peripheral API.
Abstraction of the Secure Element's mailbox interface.
For series 2 devices with a part number that is xG23 or higher, the following step is necessary for basic operation:
Clock enable:
- Note
- The high-level SE API has been moved to the SE manager, and the implementation in em_se should not be used.
- Using the SE's mailbox is not thread-safe in emlib, and accessing the SE's mailbox both in regular and IRQ context is not safe. SE operations should be performed using the SE manager if possible.
Modules |
|
Deprecated Functions
|
|
Deprecated Functions.
|
|
Data Structures |
|
struct | SE_DataTransfer_t |
SE DMA transfer descriptor.
|
|
struct | SE_Command_t |
SE Command structure to which all commands to the SE must adhere.
|
|
Functions |
|
void | writeToFifo (uint32_t value) |
Write to FIFO.
|
|
void | SE_addDataInput ( SE_Command_t *command, SE_DataTransfer_t *data) |
Add input data to a command.
|
|
void | SE_addDataOutput ( SE_Command_t *command, SE_DataTransfer_t *data) |
Add output data to a command.
|
|
void | SE_addParameter ( SE_Command_t *command, uint32_t parameter) |
Add a parameter to a command.
|
|
void | SE_executeCommand ( SE_Command_t *command) |
Execute the passed command.
|
|
bool | SE_isCommandCompleted (void) |
Check whether the running command has completed.
|
|
SE_Response_t | SE_readCommandResponse (void) |
Read the status of the previously executed command.
|
|
void | SE_waitCommandCompletion (void) |
Wait for completion of the current command.
|
|
void | SE_disableInterrupt (uint32_t flags) |
Disable one or more SE interrupts.
|
|
void | SE_enableInterrupt (uint32_t flags) |
Enable one or more SE interrupts.
|
|
Macros |
|
#define | SE_RESPONSE_MASK 0x000F0000UL |
Response status codes for the Secure Element.
|
|
#define | SE_RESPONSE_OK 0x00000000UL |
Command executed successfully or signature was successfully validated.
|
|
#define | SE_FIFO_MAX_PARAMETERS 13U |
Maximum amount of parameters supported by the hardware FIFO.
|
|
#define | SE_DATATRANSFER_STOP 0x00000001UL |
Stop datatransfer.
|
|
#define | SE_DATATRANSFER_DISCARD 0x40000000UL |
Discard datatransfer.
|
|
#define | SE_DATATRANSFER_REALIGN 0x20000000UL |
Realign datatransfer.
|
|
#define | SE_DATATRANSFER_CONSTADDRESS 0x10000000UL |
Datatransfer Const Address.
|
|
#define | SE_DATATRANSFER_LENGTH_MASK 0x0FFFFFFFUL |
Stop Length Mask.
|
|
#define | SE_MAX_PARAMETERS 4U |
Maximum amount of parameters for largest command in defined command set.
|
|
#define | SE_DATATRANSFER_DEFAULT (address, length) |
Default initialization of data transfer struct.
|
|
#define | SE_COMMAND_DEFAULT (command) |
Default initialization of command struct.
|
|
Typedefs |
|
typedef uint32_t | SE_Response_t |
Possible responses to a command.
|
|
Function Documentation
◆ writeToFifo()
|
inline |
Write to FIFO.
- Parameters
-
value
Value to write to FIFO
◆ SE_addDataInput()
void SE_addDataInput | ( | SE_Command_t * |
command,
|
SE_DataTransfer_t * |
data
|
||
) |
Add input data to a command.
This function adds a buffer of input data to the given SE command structure The buffer gets appended by reference at the end of the list of already added buffers.
- Note
- Note that this function does not copy either the data buffer or the buffer structure, so make sure to keep the data object in scope until the command has been executed by the secure element.
- Parameters
-
[in] command
Pointer to an SE command structure. [in] data
Pointer to a data transfer structure.
◆ SE_addDataOutput()
void SE_addDataOutput | ( | SE_Command_t * |
command,
|
SE_DataTransfer_t * |
data
|
||
) |
Add output data to a command.
This function adds a buffer of output data to the given command structure The buffer gets appended by reference at the end of the list of already added buffers.
- Note
- Note that this function does not copy either the data buffer or the buffer structure, so make sure to keep the data object in scope until the command has been executed by the secure element.
- Parameters
-
[in] command
Pointer to an SE command structure. [in] data
Pointer to a data transfer structure.
◆ SE_addParameter()
void SE_addParameter | ( | SE_Command_t * |
command,
|
uint32_t |
parameter
|
||
) |
Add a parameter to a command.
This function adds a parameter word to the passed command.
- Note
- Make sure to not exceed SE_MAX_PARAMETERS .
- Parameters
-
[in] command
Pointer to a filled-out SE command structure. [in] parameter
Parameter to add.
◆ SE_executeCommand()
void SE_executeCommand | ( | SE_Command_t * |
command
|
) |
Execute the passed command.
This function starts the execution of the passed command by the secure element. When started, wait for the RXINT interrupt flag, or call SE_waitCommandCompletion to busy-wait. After completion, you have to call SE_readCommandResponse to get the command's execution status.
- Parameters
-
[in] command
Pointer to a filled-out SE command structure.
◆ SE_isCommandCompleted()
|
inline |
Check whether the running command has completed.
This function polls the SE-to-host mailbox interrupt flag.
- Returns
- True if a command has completed and the result is available
◆ SE_readCommandResponse()
|
inline |
Read the status of the previously executed command.
This function reads the status of the previously executed command.
- Note
- The command response needs to be read for every executed command, and can only be read once per executed command (FIFO behavior).
- Returns
- One of the SE_RESPONSE return codes: SE_RESPONSE_OK when the command was executed successfully or a signature was successfully verified.
◆ SE_waitCommandCompletion()
|
inline |
Wait for completion of the current command.
This function "busy"-waits until the execution of the ongoing instruction has completed.
◆ SE_disableInterrupt()
|
inline |
Disable one or more SE interrupts.
- Parameters
-
[in] flags
SE interrupt sources to disable. Use a bitwise logic OR combination of valid interrupt flags for the Secure Element module (SE_CONFIGURATION_(TX/RX)INTEN).
◆ SE_enableInterrupt()
|
inline |
Enable one or more SE interrupts.
- Parameters
-
[in] flags
SE interrupt sources to enable. Use a bitwise logic OR combination of valid interrupt flags for the Secure Element module (SEMAILBOX_CONFIGURATION_TXINTEN or SEMAILBOX_CONFIGURATION_RXINTEN).
Macro Definition Documentation
◆ SE_RESPONSE_MASK
#define SE_RESPONSE_MASK 0x000F0000UL |
Response status codes for the Secure Element.
◆ SE_RESPONSE_OK
#define SE_RESPONSE_OK 0x00000000UL |
Command executed successfully or signature was successfully validated.
◆ SE_FIFO_MAX_PARAMETERS
#define SE_FIFO_MAX_PARAMETERS 13U |
Maximum amount of parameters supported by the hardware FIFO.
◆ SE_DATATRANSFER_STOP
#define SE_DATATRANSFER_STOP 0x00000001UL |
Stop datatransfer.
◆ SE_DATATRANSFER_DISCARD
#define SE_DATATRANSFER_DISCARD 0x40000000UL |
Discard datatransfer.
◆ SE_DATATRANSFER_REALIGN
#define SE_DATATRANSFER_REALIGN 0x20000000UL |
Realign datatransfer.
◆ SE_DATATRANSFER_CONSTADDRESS
#define SE_DATATRANSFER_CONSTADDRESS 0x10000000UL |
Datatransfer Const Address.
◆ SE_DATATRANSFER_LENGTH_MASK
#define SE_DATATRANSFER_LENGTH_MASK 0x0FFFFFFFUL |
Stop Length Mask.
◆ SE_MAX_PARAMETERS
#define SE_MAX_PARAMETERS 4U |
Maximum amount of parameters for largest command in defined command set.
◆ SE_DATATRANSFER_DEFAULT
#define SE_DATATRANSFER_DEFAULT | ( |
address,
|
|
length
|
|||
) |
Default initialization of data transfer struct.
◆ SE_COMMAND_DEFAULT
#define SE_COMMAND_DEFAULT | ( |
command
|
) |
Default initialization of command struct.
Typedef Documentation
◆ SE_Response_t
typedef uint32_t SE_Response_t |
Possible responses to a command.