Introduction

See HSM client for more details.

Data Structures
union	HsmVer_t
	type for reading HSMRt version. More...

struct	HsmClient_t
	This is a HSMClient type which holds the information needed by hsm client to communicate with HSM . More...

struct	NvmOtpRead_t
	This is an NvmOtpRead type which holds the information of NvmOtp row index and row data corresponding to it . For F29H85x, the rowdIdx corresponds to the Flash Offsets. For AM26x, the rowIdx corresponds to efuse row offsets. More...

struct	NvmOtpRowWrite_t
	This is an NvmOtpRowWrite type which holds the information regarding programming NvmOtp row. For F29H85x, the rowdIdx corresponds to the Flash Offsets. For AM26x, the rowIdx corresponds to efuse row offsets. More...

struct	NvmOtpRowCount_t
	This is an NvmOtpRowCount type which holds the information regarding NvmOtp row count and size of each row in bits. More...

struct	NvmOtpRowProt_t
	This is a NvmOtpRowProt type which holds the information of NvmOtp row index and protection status corresponding to the row index. This structure is not valid for f29h85x. More...

struct	KeyWriterCertHeader_t
	This is a keywriter_cert_header type which holds the information of customer key certificate and debug responce. More...

struct	FirewallRegionReq_t
	This is a FirewallRegionReq type which holds the information of Firewall region configuration. More...

struct	FirewallReq_t
	This is a FirewallReq_t type which holds the information of Firewall configuration. More...

struct	FirewallIntrReq_t
	This is a FirewallIntrReq type which holds the information of MPU Firewall request for interrupt enable, interrupt enable clear, interrupt enable status clear and fault clear. More...

struct	SWRev_t
	This is SWRev type which holds the information regarding Revision identifier and value corresponding to it . More...

struct	DKEK_t
	This is DKEK type which holds the label and context for derivation. This also holds the 256 derived KEK value which is returned by TIFS. More...

struct	RNGReq_t
	This is RNG type which holds the resultPtr for derivation which is returned by TIFS. This also holds the resultLengthPtr and DRBG Mode along with seedValue and seedSize. More...

struct	SecureBoot_Stream_t_
	This is the SecureBoot Stream type which holds the data for a specific bootloader to HSM call. This packet is needed by HSM the to do the required operation. More...

struct	FirmwareUpdateReq_t
	This is Firmware Update request structure passed to HSM core via SIPC as argument, these parameters are required by the service handler. More...

struct	OTFA_Region_t
	This is the OTFA Region structure which holds individual region specific information to be written to corresponding OTFA registers. In AM263Px and AM261x, there are 4 OTFA regions. More...

struct	OTFA_readRegion_t
	This is the OTFA Region structure which holds individual region specific information to be read from OTFA registers. More...

struct	OTFA_Config_t
	This is the entire OTFA structure which holds all regions' information 4 regions in AM263Px and AM261x. More...

struct	HsmMsg_t_
	HSM client / server message format struct. More...

Functions
union HsmVer_t_	__attribute__ ((packed)) HsmVer_t
	type for reading HSMRt version. More...

int32_t	HsmClient_checkAndWaitForBootNotification (void)
	This API waits for HSMRT load if requested and then waits for boot notification. In case of failure in HSMRT load it returns SystemP_FAILURE. More...

int32_t	HsmClient_init (SIPC_Params *params)
	Initialize the HSM client for current core. More...

void	HsmClient_deInit (void)
	De initialize the HSM client for current core. More...

void	HsmClient_SecureBootQueueInit (uint32_t configured_hsm_client_msg_queue_size)
	Customize the size of the HSM client message queue. More...

int32_t	HsmClient_getVersion (HsmClient_t HsmClient, HsmVer_t verId, uint32_t timeToWaitInTick)
	populates the current HSMRT version Id by default the hsm flag is set to HSM_FLAG_AOP for this service More...

int32_t	HsmClient_getUID (HsmClient_t HsmClient, uint8_t uid, uint32_t timeout)
	The service issued to HSM Server populates the Device UID by default the hsm flag is set to HSM_FLAG_AOP for this service. More...

int32_t	HsmClient_openDbgFirewall (HsmClient_t HsmClient, uint8_t cert, uint32_t cert_size, uint32_t timeout)
	The service issued to HSM Server verifies the certificate and by default the hsm flag is set to HSM_FLAG_AOP for this service. More...

int32_t	HsmClient_importKeyring (HsmClient_t HsmClient, uint8_t cert, uint32_t cert_size, uint32_t timeout)
	The service issued to HSM Server verifies the certificate and imports the keys from the certificate. More...

int32_t	HsmClient_readOTPRow (HsmClient_t HsmClient, NvmOtpRead_t readRow)
	The service issued to HSM Server retrieves the data of GP OTP row based on row index provided as param. More...

int32_t	HsmClient_writeOTPRow (HsmClient_t HsmClient, NvmOtpRowWrite_t writeRow)
	The service issued to HSM Server writes the data to extended OTP efuse row based on row index provided as param. More...

int32_t	HsmClient_lockOTPRow (HsmClient_t HsmClient, NvmOtpRowProt_t rowProt)
	The service issued to HSM Server sets the protection status bit of the specified row to 1. This API is not valid for F29H85x. More...

int32_t	HsmClient_getOTPRowCount (HsmClient_t HsmClient, NvmOtpRowCount_t rowCount)
	The service issued to HSM Server retrieves the count of extended OTP rows. More...

int32_t	HsmClient_getOTPRowProtection (HsmClient_t HsmClient, NvmOtpRowProt_t rowProt)
	The service issued to HSM Server retrieves the extended otp efuse row protection status. This API is not valid for F29H85x. More...

int32_t	HsmClient_procAuthBoot (HsmClient_t HsmClient, uint8_t cert, uint32_t cert_size, uint32_t timeout)
	The service issued to HSM Server helps with extended secure boot for applications. More...

int32_t	HsmClient_procAuthBootStart (HsmClient_t HsmClient, SecureBoot_Stream_t secureBootInfo)
	The service issued to HSM Server helps with extended secure boot for applications. More...

int32_t	HsmClient_procAuthBootUpdate (HsmClient_t HsmClient, SecureBoot_Stream_t secureBootInfo)
	The service issued to HSM Server helps with extended secure boot for applications. More...

int32_t	HsmClient_procAuthBootFinish (HsmClient_t HsmClient, SecureBoot_Stream_t secureBootInfo)
	The service issued to HSM Server helps with extended secure boot for applications. More...

int32_t	HsmClient_setFirewall (HsmClient_t HsmClient, FirewallReq_t FirewallReqObj, uint32_t timeout)
	The service issued to HSM Server sets the firewall for the given firewall id and region. More...

int32_t	HsmClient_FirewallIntr (HsmClient_t HsmClient, FirewallIntrReq_t FirewallIntrReqObj, uint32_t timeout)
	The service issued to HSM Server sets the firewall interrupt request for the given firewall id. More...

int32_t	HsmClient_keyWriter (HsmClient_t HsmClient, KeyWriterCertHeader_t certHeader, uint32_t timeout)
	The service issued to HSM Server verifies the certificate and process the keywriter operations,. More...

int32_t	HsmClient_readSWRev (HsmClient_t HsmClient, SWRev_t readSWRev)
	The service issued to HSM Server retrieves the SWRevision value based on identifier as param. More...

int32_t	HsmClient_writeSWRev (HsmClient_t HsmClient, SWRev_t writeSWRev)
	The service issued to HSM Server writes the SWRevision value based on identifier as param. More...

int32_t	HsmClient_getDKEK (HsmClient_t HsmClient, DKEK_t getDKEK, uint32_t timeout)
	The service issued to HSM Server retrieves the derived KEK based on identifier as param. More...

int32_t	HsmClient_register (HsmClient_t *HsmClient, uint8_t clientId)
	register a client to a particular ClientId More...

void	HsmClient_unregister (HsmClient_t *HsmClient, uint8_t clientId)
	unregister a client to a particular ClientId More...

int32_t	HsmClient_waitForBootNotify (HsmClient_t *HsmClient, uint32_t timeToWaitInTicks)
	Current core will wait for bootnotify message from HSM core. More...

int32_t	Hsmclient_loadHSMRtFirmware (HsmClient_t gHSMClient, const uint8_t pHSMRt_firmware)
	Loads the HSMRt firmware. This is typically called by SBL. More...

int32_t	Hsmclient_loadHSMRtFirmwareNonBlocking (const uint8_t *pHSMRt_firmware)
	Loads the HSMRt firmware but does wait for ROM response and boot notification. This is typically called by SBL. More...

int32_t	HsmClient_getRandomNum (HsmClient_t HsmClient, RNGReq_t getRandomNum)
	Returns the Random Number Generated. More...

int32_t	HsmClient_firmwareUpdate_CertProcess (HsmClient_t HsmClient, FirmwareUpdateReq_t pFirmwareUpdateObject)
	service request issued to HSM server to parse the certificate to validate authenticity and identify the firmware component undergoing update This service is valid only for F29H85x SOC More...

int32_t	HsmClient_firmwareUpdate_CodeProgram (HsmClient_t HsmClient, FirmwareUpdateReq_t pFirmwareUpdateObject)
	service request issued to HSM server to program the incoming firmware to device dormant banks This service is valid only for F29H85x SOC More...

int32_t	HsmClient_firmwareUpdate_CodeVerify (HsmClient_t HsmClient, FirmwareUpdateReq_t pFirmwareUpdateObject)
	service request issued to HSM server to decrypt the firmware programmed in dormant flash bank in place, perform integrity checks on the decrypted firmware and program the certificate in flash memory This service is valid only for F29H85x SOC More...

int32_t	HsmClient_VerifyROTSwitchingCertificate (HsmClient_t HsmClient, uint8_t cert, uint32_t cert_size, uint32_t timeout)
	service request issued to HSM server to validate RoT Switching Certificate More...

int32_t	HsmClient_UpdateKeyRevsion (HsmClient_t *HsmClient, uint32_t timeout)
	service request issued to HSM server to update key revision to 0x2 which changes the root of trust key from secondary keys to back up keys. More...

int32_t	HsmClient_configOTFARegions (HsmClient_t HsmClient, OTFA_Config_t OTFA_ConfigInfo, uint32_t timeout)
	Client request to configure the OTFA regions. More...

int32_t	HsmClient_readOTFARegions (HsmClient_t HsmClient, OTFA_readRegion_t OTFA_readRegion, uint32_t timeout)
	Client request to read the OTFA regions. More...

Enumerations
enum	HSM_ClientIds_t { HSM_BOOT_NOTIFY_CLIENT_ID = 0, HSM_CLIENT_ID_1, HSM_CLIENT_ID_2, HSM_CLIENT_ID_3, HSM_CLIENT_ID_4 }

Macros
#define	LABEL_AND_CONTEXT_LEN_MAX 48U

#define	HSMRT_LOAD_NOT_REQUESTED (0U)
	HSMRT load has not been requested. More...

#define	HSMRT_LOAD_REQUESTED (1U)
	HSMRT load has been requested. More...

#define	HSMRT_LOAD_FAILED (2U)
	HSMRT load has failed. More...

#define	HSMRT_LOAD_SUCCEEDED (3U)
	HSMRT load has succeeded. More...

#define	HSM_MSG_GET_VERSION (0x0002)
	GetVersion service type ID. More...

#define	HSM_MSG_BOOT_NOTIFY (0x000A)
	Boot Notify service type ID. More...

#define	HSM_MSG_GET_UID (0x9021)
	Get UID service type ID. More...

#define	HSM_MSG_OPEN_DBG_FIREWALLS (0x900C)
	Open Debug Firewalls service type ID. More...

#define	HSM_MSG_READ_OTP_ROW (0x9022)
	Read Extended otp row type ID. More...

#define	HSM_MSG_WRITE_OTP_ROW (0x9023)
	Write Extended otp row type ID. More...

#define	HSM_MSG_PROT_OTP_ROW (0x9024)
	Protect Extended otp row type ID. More...

#define	HSM_MSG_GET_OTP_ROW_PROT (0x9026)
	Get Extended otp row protection type ID. More...

#define	HSM_MSG_GET_OTP_ROW_COUNT (0x9027)
	Get Extended otp row count service type ID. More...

#define	HSM_MSG_PROC_AUTH_BOOT (0xC120)
	Secure Boot service type ID. More...

#define	HSM_MSG_PROC_AUTH_BOOT_START (0xC12A)
	Secure Boot Streaming Start service type ID. More...

#define	HSM_MSG_PROC_AUTH_BOOT_UPDATE (0xC12B)
	Secure Boot Streaming Update service type ID. More...

#define	HSM_MSG_PROC_AUTH_BOOT_FINISH (0xC12C)
	Secure Boot Streaming Finish service type ID. More...

#define	HSM_MSG_SET_FIREWALL (0x9000U)
	Set Firewall service type ID. More...

#define	HSM_MSG_SET_FIREWALL_INTR (0x9002)
	Set Firewall Interrupt service type ID. More...

#define	HSM_KEYWRITER_SEND_CUST_KEY_CERT (0x9028)
	send KeyWriter customer key certificate More...

#define	HSM_MSG_READ_SWREV (0x9033)
	Read Software Revision service type ID. More...

#define	HSM_MSG_WRITE_SWREV (0x9032)
	Write Software Revision service type ID. More...

#define	HSM_MSG_GET_DKEK (0x9029)
	Get DKEK service type ID. More...

#define	HSM_MSG_GET_RAND (0x9001)
	Get RNG service type ID. More...

#define	HSM_MSG_KEYRING_IMPORT (0x9039)
	Get KEYRING import service type ID. More...

#define	HSM_MSG_FW_UPDATE_CERT_PROCESS (0x9040)
	Process certificate during firmware update/code provisioning. More...

#define	HSM_MSG_FW_UPDATE_CODE_PROGRAM (0x9041)
	Program firmware during firmware update/code provisioning. More...

#define	HSM_MSG_FW_UPDATE_CODE_VERIFY (0x9043)
	Program firmware during firmware update/code provisioning. More...

#define	HSM_MSG_VERIFY_ROT_CERT (0x9044)
	Veriy RoT Switching Certificate Service type ID. More...

#define	HSM_MSG_UPDATE_KEY_REV (0x9045)
	Update Key Revision Service type ID. More...

#define	HSM_MSG_CONFIGURE_OTFA (0x9056)
	Configure OTFA service ID. More...

#define	HSM_MSG_READ_OTFA (0x9057)
	Read OTFA service ID. More...

#define	HSM_FLAG_AOP (0x11)
	HSM FLAG used by HSM client to indicate that it expects ACK messasge from HSM and will wait for a response message. More...

#define	HSM_FLAG_NAOP (0x22)
	HSM FLAG used by HSM client to indicate that it does not expects an ACK messasge from HSM and will not wait for a response message. More...

#define	HSM_FLAG_ACK (0xAA)
	HSM FLAG used by HSM server to indicate that the request has been processed. More...

#define	HSM_FLAG_NACK (0x55)
	HSM FLAG used by HSM server to indicate that the request has not been processed. More...

#define	HSM_CLIENT_ID (0x01)
	HSM server SIPC client Id. More...

#define	HSM_UID_SIZE (64U)
	UID or Unique ID is a device specific ID of 64 bytes. More...

#define	HSM_DBG_CERT_SIZE (4096U)
	Maximum Certificate Size allowed for Debug Open. More...

#define	HSM_KEYRING_CERT_SIZE (10280U)
	Maximum Certificate Size allowed for Keyring Import. More...

#define	HSM_FIRMWARE_CHUNK_SIZE (16384U)
	Maximum firmware Size allowed for code provisioning. More...

Macro Definition Documentation

◆ LABEL_AND_CONTEXT_LEN_MAX

#define LABEL_AND_CONTEXT_LEN_MAX 48U

◆ HSMRT_LOAD_NOT_REQUESTED

#define HSMRT_LOAD_NOT_REQUESTED (0U)

HSMRT load has not been requested.

◆ HSMRT_LOAD_REQUESTED

#define HSMRT_LOAD_REQUESTED (1U)

HSMRT load has been requested.

◆ HSMRT_LOAD_FAILED

#define HSMRT_LOAD_FAILED (2U)

HSMRT load has failed.

◆ HSMRT_LOAD_SUCCEEDED

#define HSMRT_LOAD_SUCCEEDED (3U)

HSMRT load has succeeded.

◆ HSM_MSG_GET_VERSION

#define HSM_MSG_GET_VERSION (0x0002)

GetVersion service type ID.

◆ HSM_MSG_BOOT_NOTIFY

#define HSM_MSG_BOOT_NOTIFY (0x000A)

Boot Notify service type ID.

◆ HSM_MSG_GET_UID

#define HSM_MSG_GET_UID (0x9021)

Get UID service type ID.

◆ HSM_MSG_OPEN_DBG_FIREWALLS

#define HSM_MSG_OPEN_DBG_FIREWALLS (0x900C)

Open Debug Firewalls service type ID.

◆ HSM_MSG_READ_OTP_ROW

#define HSM_MSG_READ_OTP_ROW (0x9022)

Read Extended otp row type ID.

◆ HSM_MSG_WRITE_OTP_ROW

#define HSM_MSG_WRITE_OTP_ROW (0x9023)

Write Extended otp row type ID.

◆ HSM_MSG_PROT_OTP_ROW

#define HSM_MSG_PROT_OTP_ROW (0x9024)

Protect Extended otp row type ID.

◆ HSM_MSG_GET_OTP_ROW_PROT

#define HSM_MSG_GET_OTP_ROW_PROT (0x9026)

Get Extended otp row protection type ID.

◆ HSM_MSG_GET_OTP_ROW_COUNT

#define HSM_MSG_GET_OTP_ROW_COUNT (0x9027)

Get Extended otp row count service type ID.

◆ HSM_MSG_PROC_AUTH_BOOT

#define HSM_MSG_PROC_AUTH_BOOT (0xC120)

Secure Boot service type ID.

◆ HSM_MSG_PROC_AUTH_BOOT_START

#define HSM_MSG_PROC_AUTH_BOOT_START (0xC12A)

Secure Boot Streaming Start service type ID.

◆ HSM_MSG_PROC_AUTH_BOOT_UPDATE

#define HSM_MSG_PROC_AUTH_BOOT_UPDATE (0xC12B)

Secure Boot Streaming Update service type ID.

◆ HSM_MSG_PROC_AUTH_BOOT_FINISH

#define HSM_MSG_PROC_AUTH_BOOT_FINISH (0xC12C)

Secure Boot Streaming Finish service type ID.

◆ HSM_MSG_SET_FIREWALL

#define HSM_MSG_SET_FIREWALL (0x9000U)

Set Firewall service type ID.

◆ HSM_MSG_SET_FIREWALL_INTR

#define HSM_MSG_SET_FIREWALL_INTR (0x9002)

Set Firewall Interrupt service type ID.

◆ HSM_KEYWRITER_SEND_CUST_KEY_CERT

#define HSM_KEYWRITER_SEND_CUST_KEY_CERT (0x9028)

send KeyWriter customer key certificate

◆ HSM_MSG_READ_SWREV

#define HSM_MSG_READ_SWREV (0x9033)

Read Software Revision service type ID.

◆ HSM_MSG_WRITE_SWREV

#define HSM_MSG_WRITE_SWREV (0x9032)

Write Software Revision service type ID.

◆ HSM_MSG_GET_DKEK

#define HSM_MSG_GET_DKEK (0x9029)

Get DKEK service type ID.

◆ HSM_MSG_GET_RAND

#define HSM_MSG_GET_RAND (0x9001)

Get RNG service type ID.

◆ HSM_MSG_KEYRING_IMPORT

#define HSM_MSG_KEYRING_IMPORT (0x9039)

Get KEYRING import service type ID.

◆ HSM_MSG_FW_UPDATE_CERT_PROCESS

#define HSM_MSG_FW_UPDATE_CERT_PROCESS (0x9040)

Process certificate during firmware update/code provisioning.

◆ HSM_MSG_FW_UPDATE_CODE_PROGRAM

#define HSM_MSG_FW_UPDATE_CODE_PROGRAM (0x9041)

Program firmware during firmware update/code provisioning.

◆ HSM_MSG_FW_UPDATE_CODE_VERIFY

#define HSM_MSG_FW_UPDATE_CODE_VERIFY (0x9043)

Program firmware during firmware update/code provisioning.

◆ HSM_MSG_VERIFY_ROT_CERT

#define HSM_MSG_VERIFY_ROT_CERT (0x9044)

Veriy RoT Switching Certificate Service type ID.

◆ HSM_MSG_UPDATE_KEY_REV

#define HSM_MSG_UPDATE_KEY_REV (0x9045)

Update Key Revision Service type ID.

◆ HSM_MSG_CONFIGURE_OTFA

#define HSM_MSG_CONFIGURE_OTFA (0x9056)

Configure OTFA service ID.

◆ HSM_MSG_READ_OTFA

#define HSM_MSG_READ_OTFA (0x9057)

Read OTFA service ID.

◆ HSM_FLAG_AOP

#define HSM_FLAG_AOP (0x11)

HSM FLAG used by HSM client to indicate that it expects ACK messasge from HSM and will wait for a response message.

◆ HSM_FLAG_NAOP

#define HSM_FLAG_NAOP (0x22)

HSM FLAG used by HSM client to indicate that it does not expects an ACK messasge from HSM and will not wait for a response message.

◆ HSM_FLAG_ACK

#define HSM_FLAG_ACK (0xAA)

HSM FLAG used by HSM server to indicate that the request has been processed.

◆ HSM_FLAG_NACK

#define HSM_FLAG_NACK (0x55)

HSM FLAG used by HSM server to indicate that the request has not been processed.

◆ HSM_CLIENT_ID

#define HSM_CLIENT_ID (0x01)

HSM server SIPC client Id.

◆ HSM_UID_SIZE

#define HSM_UID_SIZE (64U)

UID or Unique ID is a device specific ID of 64 bytes.

◆ HSM_DBG_CERT_SIZE

#define HSM_DBG_CERT_SIZE (4096U)

Maximum Certificate Size allowed for Debug Open.

◆ HSM_KEYRING_CERT_SIZE

#define HSM_KEYRING_CERT_SIZE (10280U)

Maximum Certificate Size allowed for Keyring Import.

◆ HSM_FIRMWARE_CHUNK_SIZE

#define HSM_FIRMWARE_CHUNK_SIZE (16384U)

Maximum firmware Size allowed for code provisioning.

Enumeration Type Documentation

◆ HSM_ClientIds_t

enum HSM_ClientIds_t

Enumerator
HSM_BOOT_NOTIFY_CLIENT_ID
HSM_CLIENT_ID_1
HSM_CLIENT_ID_2
HSM_CLIENT_ID_3
HSM_CLIENT_ID_4

Function Documentation

◆ attribute()

union HsmVer_t_ __attribute__ ( (packed) )

type for reading HSMRt version.

HSM client / server message format struct.

This is the SecureBoot Stream type which holds the data for a specific bootloader to HSM call. This packet is needed by HSM the to do the required operation.

◆ HsmClient_checkAndWaitForBootNotification()

int32_t HsmClient_checkAndWaitForBootNotification ( void )

This API waits for HSMRT load if requested and then waits for boot notification. In case of failure in HSMRT load it returns SystemP_FAILURE.

Returns

SystemP_SUCCESS if HSMRT load is successful.
SystemP_FAILURE if HSMRT load fails.

◆ HsmClient_init()

int32_t HsmClient_init ( SIPC_Params * params )

Initialize the HSM client for current core.

Parameters

params [IN] SIPC_notify params.

Returns

SystemP_SUCCESS if init sequence successful.
SystemP_FAILURE if init sequence fails.

◆ HsmClient_deInit()

void HsmClient_deInit ( void )

De initialize the HSM client for current core.

◆ HsmClient_SecureBootQueueInit()

void HsmClient_SecureBootQueueInit ( uint32_t configured_hsm_client_msg_queue_size )

Customize the size of the HSM client message queue.

Parameters

configured_hsm_client_msg_queue_size Desired size of the HSM client message queue passed by the user.

◆ HsmClient_getVersion()

int32_t HsmClient_getVersion	(	HsmClient_t *	HsmClient,
		HsmVer_t *	verId,
		uint32_t	timeToWaitInTick
	)

populates the current HSMRT version Id by default the hsm flag is set to HSM_FLAG_AOP for this service

Parameters

timeToWaitInTick	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] Client object which is using this getversion API.
verId	[OUT] populates HsmVer_t struct which describes current version. This object's memory address needs to be cache aligned.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_getUID()

int32_t HsmClient_getUID	(	HsmClient_t *	HsmClient,
		uint8_t *	uid,
		uint32_t	timeout
	)

The service issued to HSM Server populates the Device UID by default the hsm flag is set to HSM_FLAG_AOP for this service.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] Client object which is using this getUID API.
uid	[OUT] populates UID value.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_openDbgFirewall()

int32_t HsmClient_openDbgFirewall	(	HsmClient_t *	HsmClient,
		uint8_t *	cert,
		uint32_t	cert_size,
		uint32_t	timeout
	)

The service issued to HSM Server verifies the certificate and by default the hsm flag is set to HSM_FLAG_AOP for this service.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] Client object which is using this openDbgFirewalls API.
cert	[IN] point to the location of certificate in the device memory.
cert_size	[IN] size of certificate.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_importKeyring()

int32_t HsmClient_importKeyring	(	HsmClient_t *	HsmClient,
		uint8_t *	cert,
		uint32_t	cert_size,
		uint32_t	timeout
	)

The service issued to HSM Server verifies the certificate and imports the keys from the certificate.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] Client object which is using this importKeyring API.
cert	[IN] point to the location of certificate in the device memory.
cert_size	[IN] size of certificate.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_readOTPRow()

int32_t HsmClient_readOTPRow	(	HsmClient_t *	HsmClient,
		NvmOtpRead_t *	readRow
	)

The service issued to HSM Server retrieves the data of GP OTP row based on row index provided as param.

Parameters

HsmClient	[IN] HsmClient object.
readRow	[IN] populates NvmOtpRead_t struct with rowData corresponding to rowIdx.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_writeOTPRow()

int32_t HsmClient_writeOTPRow	(	HsmClient_t *	HsmClient,
		NvmOtpRowWrite_t *	writeRow
	)

The service issued to HSM Server writes the data to extended OTP efuse row based on row index provided as param.

Parameters

HsmClient	[IN] HsmClient object.
writeRow	[IN] populates NvmOtpRowWrite_t struct with rowData corresponding to rowIdx.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_lockOTPRow()

int32_t HsmClient_lockOTPRow	(	HsmClient_t *	HsmClient,
		NvmOtpRowProt_t *	rowProt
	)

The service issued to HSM Server sets the protection status bit of the specified row to 1. This API is not valid for F29H85x.

Parameters

HsmClient	[IN] HsmClient object.
rowProt	[IN] Pointer to NvmOtpRowProt_t struct which contains the row index and row protection status

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_getOTPRowCount()

int32_t HsmClient_getOTPRowCount	(	HsmClient_t *	HsmClient,
		NvmOtpRowCount_t *	rowCount
	)

The service issued to HSM Server retrieves the count of extended OTP rows.

Parameters

HsmClient	[IN] HsmClient object.
rowCount	[IN] Pointer to NvmOtpRowCount_t struct which is populated by HSM server with row count and row size

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_getOTPRowProtection()

int32_t HsmClient_getOTPRowProtection	(	HsmClient_t *	HsmClient,
		NvmOtpRowProt_t *	rowProt
	)

The service issued to HSM Server retrieves the extended otp efuse row protection status. This API is not valid for F29H85x.

Parameters

HsmClient	[IN] HsmClient object.
rowProt	[IN] Pointer to NvmOtpRowProt_t struct which is populated by HSM server with row protection status

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_procAuthBoot()

int32_t HsmClient_procAuthBoot	(	HsmClient_t *	HsmClient,
		uint8_t *	cert,
		uint32_t	cert_size,
		uint32_t	timeout
	)

The service issued to HSM Server helps with extended secure boot for applications.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] Client object which is using this openDbgFirewalls API.
cert	[IN] point to the location of certificate in the device memory.
cert_size	[IN] size of certificate.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_procAuthBootStart()

int32_t HsmClient_procAuthBootStart	(	HsmClient_t *	HsmClient,
		SecureBoot_Stream_t *	secureBootInfo
	)

The service issued to HSM Server helps with extended secure boot for applications.

Parameters

HsmClient	[IN] Client object which is using this openDbgFirewalls API.
secureBootInfo	[IN] pointer to the secure boot information object in shared memory.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_procAuthBootUpdate()

int32_t HsmClient_procAuthBootUpdate	(	HsmClient_t *	HsmClient,
		SecureBoot_Stream_t *	secureBootInfo
	)

The service issued to HSM Server helps with extended secure boot for applications.

Parameters

HsmClient	[IN] Client object which is using this openDbgFirewalls API.
secureBootInfo	[IN] pointer to the secure boot information object in shared memory.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_procAuthBootFinish()

int32_t HsmClient_procAuthBootFinish	(	HsmClient_t *	HsmClient,
		SecureBoot_Stream_t *	secureBootInfo
	)

The service issued to HSM Server helps with extended secure boot for applications.

Parameters

HsmClient	[IN] Client object which is using this openDbgFirewalls API.
secureBootInfo	[IN] pointer to the secure boot information object in shared memory

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_setFirewall()

int32_t HsmClient_setFirewall	(	HsmClient_t *	HsmClient,
		FirewallReq_t *	FirewallReqObj,
		uint32_t	timeout
	)

The service issued to HSM Server sets the firewall for the given firewall id and region.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] HsmClient object.
FirewallReqObj	[IN] Pointer to FirewallReq_t struct which contains information required for HSM to process set firewall request.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_FirewallIntr()

int32_t HsmClient_FirewallIntr	(	HsmClient_t *	HsmClient,
		FirewallIntrReq_t *	FirewallIntrReqObj,
		uint32_t	timeout
	)

The service issued to HSM Server sets the firewall interrupt request for the given firewall id.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] HsmClient object.
FirewallIntrReqObj	[IN] Pointer to FirewallIntrReq_t struct which contains information required for HSM to process firewall interrupt request.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_keyWriter()

int32_t HsmClient_keyWriter	(	HsmClient_t *	HsmClient,
		KeyWriterCertHeader_t *	certHeader,
		uint32_t	timeout
	)

The service issued to HSM Server verifies the certificate and process the keywriter operations,.

Parameters

HsmClient	[IN] Client object which is using this API.
certHeader	[IN] point to the location of certificate in the device memory. This object's memory address needs to be cache aligned.
timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_readSWRev()

int32_t HsmClient_readSWRev	(	HsmClient_t *	HsmClient,
		SWRev_t *	readSWRev
	)

The service issued to HSM Server retrieves the SWRevision value based on identifier as param.

Parameters

HsmClient	[IN] HsmClient object.
readSWRev	[IN] populates SWRev_t struct with SWRev value corresponding to identifier.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_writeSWRev()

int32_t HsmClient_writeSWRev	(	HsmClient_t *	HsmClient,
		SWRev_t *	writeSWRev
	)

The service issued to HSM Server writes the SWRevision value based on identifier as param.

Parameters

HsmClient	[IN] HsmClient object.
writeSWRev	[IN] updates the SWRev efuses with SWRev value corresponding to identifier.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_getDKEK()

int32_t HsmClient_getDKEK	(	HsmClient_t *	HsmClient,
		DKEK_t *	getDKEK,
		uint32_t	timeout
	)

The service issued to HSM Server retrieves the derived KEK based on identifier as param.

The service issued to HSM Server retrieves the derived KEK.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] HsmClient object.
getDKEK	[IN] Pointer to DKEK_t which contains the request structure for Derived KEK.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_register()

int32_t HsmClient_register	(	HsmClient_t *	HsmClient,
		uint8_t	clientId
	)

register a client to a particular ClientId

Parameters

HsmClient	[IN] HsmClient object.
clientId	[IN] enable HSM <--> R5 communication for given clientID

Returns

SystemP_SUCCESS if clientId is available
SystemP_FAILURE if clientId is not available or already in use.

◆ HsmClient_unregister()

void HsmClient_unregister	(	HsmClient_t *	HsmClient,
		uint8_t	clientId
	)

unregister a client to a particular ClientId

Parameters

HsmClient	[IN] HsmClient object
clientId	[IN] disable HSM <--> R5 communication for given clientId

◆ HsmClient_waitForBootNotify()

int32_t HsmClient_waitForBootNotify	(	HsmClient_t *	HsmClient,
		uint32_t	timeToWaitInTicks
	)

Current core will wait for bootnotify message from HSM core.

Parameters

HsmClient	[IN] HsmClient object
timeToWaitInTicks	[IN] amount of time to block waiting for semaphore to be available, in units of SystemP_timeout if timeout exception occours.system ticks (see KERNEL_DPL_CLOCK_PAGE)

Returns

SystemP_SUCCESS -: when BootNotify received
SystemP_FAILURE -: if faulty msg received

◆ Hsmclient_loadHSMRtFirmware()

int32_t Hsmclient_loadHSMRtFirmware	(	HsmClient_t *	gHSMClient,
		const uint8_t *	pHSMRt_firmware
	)

Loads the HSMRt firmware. This is typically called by SBL.

Parameters

gHSMClient	[IN] Pointer to registered HSM Client
pHSMRt_firmware	[IN] Pointer to signed HSMRt binary

Returns: SystemP_SUCCESS on success, else SystemP_FAILURE

◆ Hsmclient_loadHSMRtFirmwareNonBlocking()

int32_t Hsmclient_loadHSMRtFirmwareNonBlocking ( const uint8_t * pHSMRt_firmware )

Loads the HSMRt firmware but does wait for ROM response and boot notification. This is typically called by SBL.

Parameters

pHSMRt_firmware [IN] Pointer to signed HSMRt binary

Returns: SystemP_SUCCESS on success, else SystemP_FAILURE

◆ HsmClient_getRandomNum()

int32_t HsmClient_getRandomNum	(	HsmClient_t *	HsmClient,
		RNGReq_t *	getRandomNum
	)

Returns the Random Number Generated.

Parameters

HsmClient	[IN] HsmClient object
getRandomNum	[IN] Pointer to RNGReq_t which contains the request structure for Random Number Generated.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_firmwareUpdate_CertProcess()

int32_t HsmClient_firmwareUpdate_CertProcess	(	HsmClient_t *	HsmClient,
		FirmwareUpdateReq_t *	pFirmwareUpdateObject
	)

service request issued to HSM server to parse the certificate to validate authenticity and identify the firmware component undergoing update This service is valid only for F29H85x SOC

Parameters

HsmClient	[IN] Client object which is using this API.
pFirmwareUpdateObject	[IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_firmwareUpdate_CodeProgram()

int32_t HsmClient_firmwareUpdate_CodeProgram	(	HsmClient_t *	HsmClient,
		FirmwareUpdateReq_t *	pFirmwareUpdateObject
	)

service request issued to HSM server to program the incoming firmware to device dormant banks This service is valid only for F29H85x SOC

Parameters

HsmClient	[IN] Client object which is using this API.
pFirmwareUpdateObject	[IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_firmwareUpdate_CodeVerify()

int32_t HsmClient_firmwareUpdate_CodeVerify	(	HsmClient_t *	HsmClient,
		FirmwareUpdateReq_t *	pFirmwareUpdateObject
	)

service request issued to HSM server to decrypt the firmware programmed in dormant flash bank in place, perform integrity checks on the decrypted firmware and program the certificate in flash memory This service is valid only for F29H85x SOC

Parameters

HsmClient	[IN] Client object which is using this API.
pFirmwareUpdateObject	[IN] Pointer to arguments to be passed to HSM core via SIPC.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_VerifyROTSwitchingCertificate()

int32_t HsmClient_VerifyROTSwitchingCertificate	(	HsmClient_t *	HsmClient,
		uint8_t *	cert,
		uint32_t	cert_size,
		uint32_t	timeout
	)

service request issued to HSM server to validate RoT Switching Certificate

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] Client object which is using this RoT Switching API.
cert	[IN] point to the location of certificate in the device memory.
cert_size	[IN] size of certificate.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_UpdateKeyRevsion()

int32_t HsmClient_UpdateKeyRevsion	(	HsmClient_t *	HsmClient,
		uint32_t	timeout
	)

service request issued to HSM server to update key revision to 0x2 which changes the root of trust key from secondary keys to back up keys.

Parameters

timeout	[IN] amount of time to block waiting for semaphore to be available, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)
HsmClient	[IN] Client object which is using this RoT Switching API.

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.
SystemP_TIMEOUT if timeout exception occours.

◆ HsmClient_configOTFARegions()

int32_t HsmClient_configOTFARegions	(	HsmClient_t *	HsmClient,
		OTFA_Config_t *	OTFA_ConfigInfo,
		uint32_t	timeout
	)

Client request to configure the OTFA regions.

Parameters

HsmClient	[IN] HsmClient object
OTFA_ConfigInfo	[IN] OTFA Config Info
timeout	[IN] timeout

Returns

SystemP_SUCCESS if returns successfully
SystemP_FAILURE if NACK message is received or client id not registered.

◆ HsmClient_readOTFARegions()

int32_t HsmClient_readOTFARegions	(	HsmClient_t *	HsmClient,
		OTFA_readRegion_t *	OTFA_readRegion,
		uint32_t	timeout
	)

Client request to read the OTFA regions.

Parameters

HsmClient	[IN] HsmClient object
OTFA_readRegion	[IN] OTFA Read Region
timeout	[IN] timeout

Returns

SystemP_SUCCESS if reading done successfully
SystemP_FAILURE if NACK message is received or client id not registered.

Introduction

Data Structures

Functions

Enumerations

Macros

Macro Definition Documentation

◆ LABEL_AND_CONTEXT_LEN_MAX

◆ HSMRT_LOAD_NOT_REQUESTED

◆ HSMRT_LOAD_REQUESTED

◆ HSMRT_LOAD_FAILED

◆ HSMRT_LOAD_SUCCEEDED

◆ HSM_MSG_GET_VERSION

◆ HSM_MSG_BOOT_NOTIFY

◆ HSM_MSG_GET_UID

◆ HSM_MSG_OPEN_DBG_FIREWALLS

◆ HSM_MSG_READ_OTP_ROW

◆ HSM_MSG_WRITE_OTP_ROW

◆ HSM_MSG_PROT_OTP_ROW

◆ HSM_MSG_GET_OTP_ROW_PROT

◆ HSM_MSG_GET_OTP_ROW_COUNT

◆ HSM_MSG_PROC_AUTH_BOOT

◆ HSM_MSG_PROC_AUTH_BOOT_START

◆ HSM_MSG_PROC_AUTH_BOOT_UPDATE

◆ HSM_MSG_PROC_AUTH_BOOT_FINISH

◆ HSM_MSG_SET_FIREWALL

◆ HSM_MSG_SET_FIREWALL_INTR

◆ HSM_KEYWRITER_SEND_CUST_KEY_CERT

◆ HSM_MSG_READ_SWREV

◆ HSM_MSG_WRITE_SWREV

◆ HSM_MSG_GET_DKEK

◆ HSM_MSG_GET_RAND

◆ HSM_MSG_KEYRING_IMPORT

◆ HSM_MSG_FW_UPDATE_CERT_PROCESS

◆ HSM_MSG_FW_UPDATE_CODE_PROGRAM

◆ HSM_MSG_FW_UPDATE_CODE_VERIFY

◆ HSM_MSG_VERIFY_ROT_CERT

◆ HSM_MSG_UPDATE_KEY_REV

◆ HSM_MSG_CONFIGURE_OTFA

◆ HSM_MSG_READ_OTFA

◆ HSM_FLAG_AOP

◆ HSM_FLAG_NAOP

◆ HSM_FLAG_ACK

◆ HSM_FLAG_NACK

◆ HSM_CLIENT_ID

◆ HSM_UID_SIZE

◆ HSM_DBG_CERT_SIZE

◆ HSM_KEYRING_CERT_SIZE

◆ HSM_FIRMWARE_CHUNK_SIZE

Enumeration Type Documentation

◆ HSM_ClientIds_t

Function Documentation

◆ __attribute__()

◆ HsmClient_checkAndWaitForBootNotification()

◆ HsmClient_init()

◆ HsmClient_deInit()

◆ HsmClient_SecureBootQueueInit()

◆ HsmClient_getVersion()

◆ HsmClient_getUID()

◆ HsmClient_openDbgFirewall()

◆ HsmClient_importKeyring()

◆ HsmClient_readOTPRow()

◆ HsmClient_writeOTPRow()

◆ HsmClient_lockOTPRow()

◆ HsmClient_getOTPRowCount()

◆ HsmClient_getOTPRowProtection()

◆ HsmClient_procAuthBoot()

◆ HsmClient_procAuthBootStart()

◆ HsmClient_procAuthBootUpdate()

◆ HsmClient_procAuthBootFinish()

◆ HsmClient_setFirewall()

◆ HsmClient_FirewallIntr()

◆ HsmClient_keyWriter()

◆ HsmClient_readSWRev()

◆ HsmClient_writeSWRev()

◆ HsmClient_getDKEK()

◆ HsmClient_register()

◆ HsmClient_unregister()

◆ HsmClient_waitForBootNotify()

◆ Hsmclient_loadHSMRtFirmware()

◆ Hsmclient_loadHSMRtFirmwareNonBlocking()

◆ attribute()