SA LLD Functions
[SA LLD Module API]

COMMON (Common Interface) APIs



int16_t Sa_getBufferReq (Sa_SizeCfg_t *sizeCfg, int sizes[], int aligns[])
 Sa_getBufferReq returns the memory requirements for the SALLD instance.
int16_t Sa_create (Sa_Config_t *cfg, void *bases[], Sa_Handle *pHandle)
 Sa_create creates the SA LLD instance. It initializes the SALLD instance and its corresponding instance structure based on channel configuration data such as the call-out table, and etc.
int16_t Sa_start (Sa_Handle handle, Sa_Config_t *cfg)
 Sa_start activates the SA LLD instance.
int16_t Sa_getShadowHandle (Sa_Handle handle, Sa_Handle *shandle)
 Sa_getShadowHandle queries the shadow system handle.
int16_t Sa_close (Sa_Handle handle, void *bases[])
 Sa_close deactivates the SA LLD instance.
int16_t Sa_getSysStats (Sa_Handle handle, Sa_SysStats_t *stats)
 This function obtains SALLD system statistics.
Sa_State_t Sa_resetControl (Sa_Handle handle, Sa_State_t newState)
 This function controls the reset state of the SA Sub-System.
int16_t Sa_downloadImage (Sa_Handle handle, int modId, void *image, int sizeBytes)
 This function downloads a PDSP image to a PDSP core within the SA sub-system.
int16_t Sa_rngInit (Sa_Handle handle, Sa_RngConfigParams_t *cfg)
 The function is called to initialize and configure the RNG (Random Number Generator) module inside SA.
int16_t Sa_getRandomNum (Sa_Handle handle, uint16_t f_isr, Sa_RngData_t *rnd)
 This function returns a 64-bit true random number.
int16_t Sa_rngClose (Sa_Handle handle)
 Sa_rngClose decativates the SA RNG module.
int16_t Sa_pkaInit (Sa_Handle handle)
 This function initializes the PKA (Public Key Accelerator) module inside SA.
int16_t Sa_pkaOperation (Sa_Handle handle, Sa_PkaReqInfo_t *pkaReqInfo)
 This function triggers a large vector arithmetic operation through the PKA module.
int16_t Sa_pkaClose (Sa_Handle handle)
 Sa_pkaClose decativates the SA PKA module.
uint32_t Sa_getID (Sa_Handle handle)
 This function returns the SA system ID associated with the specified handle.
uint32_t Sa_getVersion (void)
 Sa_getVersion returns the SA LLD version information.
const char * Sa_getVersionStr (void)
 Sa_getVersionStr returns the SA LLD version string.
int16_t Sa_getPDSPVersion (Sa_Handle handle, int modId, uint32_t *pVersion)
 Sa_getPDSPVersion returns the SA PDSP version information.

CHANNEL (Channel-Specific) APIs



int16_t Sa_chanGetBufferReq (Sa_ChanSizeCfg_t *sizeCfg, int sizes[], int aligns[])
 Sa_chanGetBufferReq returns the memory requirements for an SALLD channel.
int16_t Sa_chanCreate (Sa_Handle handle, Sa_ChanConfig_t *cfg, void *bases[], Sa_ChanHandle *pChanHdl)
 Sa_chanCreate creates the SALLD channel. It initializes an instance of SALLD channel and its corresponding instance structure based on channel configuration data such as the security protocol, and etc.
int16_t Sa_chanClose (Sa_ChanHandle handle, void *bases[])
 Sa_chanClose decativates the SALLD channel. It clears the SALLD channel instance. All the associated memory buffers can be freed after this call.
int16_t Sa_chanControl (Sa_ChanHandle handle, Sa_ChanCtrlInfo_t *chanCtrlInfo)
 This function controls the operations of a channel instance of SALLD. It is used to configure and/or re-configure the SALLD channel with various control information. This function should be called multiple times to configure and activate the SALLD channel during the call setup period. Then it is typically called to perform re-key operation subsequently.
int16_t Sa_chanStart (Sa_ChanHandle handle)
 This function activates the local channel instance at other DSP cores. It should be called once at any other DSP cores which invoke the same SALLD channel that is created and configured at the master core. It is up to the master core to make the channel handle public and accessible by other DSP cores after channel creation and configuration. The following APIs are supported at slave cores.

  • Sa_chanReceiveData
  • Sa_chanSendData
  • Sa_chanGetStats
  • Sa_chanGetID.

int16_t Sa_chanGetShadowHandle (Sa_ChanHandle handle, Sa_ChanHandle *shandle)
 Sa_chanGetShadowHandle queries the shadow channel handle.
int16_t Sa_chanReceiveData (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo)
 This function processes packets received from the network. It performs protocol-specific post-SA operations on the decrypted and/or integrity-verified data packet. It also performs the actual decryption/authentication operation in SW-only mode.
int16_t Sa_chanSendData (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo, uint16_t clear)
 This function processes the data packet to the networks. It performs protocol-specific operations to prepare the data packets to be encrypted and/or authenticated by the SA. It also performs the actual encryption and/or authentication in the SW-only mode.
int16_t Sa_chanGetStats (Sa_ChanHandle handle, uint16_t flags, Sa_Stats_t *stats)
 This function obtains SALLD channel protocol-specific statistics.
uint32_t Sa_chanGetID (Sa_ChanHandle handle)
 Sa_chanGetID returns the SA channel ID associated with the specified handle.
int16_t Sa_chanGetSwInfo (Sa_ChanHandle handle, uint16_t dir, Sa_SWInfo_t *pChanSwInfo)
 Sa_chanGetSwInfo returns the SA-specific software information required for all packets to be delivered to SA.

Utility APIs



uint16_t Sa_isScBufFree (uint8_t *scBuf)
 This function verifies whether the security context buffer has been freed by SA.

Function Documentation

int16_t Sa_chanClose ( Sa_ChanHandle  handle,
void *  bases[] 
)

Sa_chanClose decativates the SALLD channel. It clears the SALLD channel instance. All the associated memory buffers can be freed after this call.

Parameters:
[in] handle SALLD channel instance identifier
[out] bases Array of the memory buffer base addresses
Return values:
Value SALLD Function Return Codes
int16_t Sa_chanControl ( Sa_ChanHandle  handle,
Sa_ChanCtrlInfo_t chanCtrlInfo 
)

This function controls the operations of a channel instance of SALLD. It is used to configure and/or re-configure the SALLD channel with various control information. This function should be called multiple times to configure and activate the SALLD channel during the call setup period. Then it is typically called to perform re-key operation subsequently.

Parameters:
[in] handle SALLD channel instance identifier.
[in] chanCtrlInfo Pointer to SALLD channel control config structure.
Return values:
Value SALLD Function Return Codes
See also:
Sa_ChanCtrlInfo_t
int16_t Sa_chanCreate ( Sa_Handle  handle,
Sa_ChanConfig_t cfg,
void *  bases[],
Sa_ChanHandle pChanHdl 
)

Sa_chanCreate creates the SALLD channel. It initializes an instance of SALLD channel and its corresponding instance structure based on channel configuration data such as the security protocol, and etc.

Parameters:
[in] handle SALLD instance identifier.
[in] cfg Configuration information
[in] bases Array of the memory buffer base addresses
[out] pChanHdl Channel handle. This is a pointer to an initialized instance structure.
Return values:
Value SALLD Function Return Codes
Note:
The channel buffers should be allocated from global accessible memory blocks and global addresses should be used if this channel is expected to be shared among multiple cores.
int16_t Sa_chanGetBufferReq ( Sa_ChanSizeCfg_t sizeCfg,
int  sizes[],
int  aligns[] 
)

Sa_chanGetBufferReq returns the memory requirements for an SALLD channel.

This function returns the memory buffer requirements in terms of the size and alignment array. The SA Channel requires only one memory block as described below:

  • SA Channel Instance: SA channel instance data
Parameters:
[in] sizeCfg Size configuration information
[out] sizes Array of size requirements
[out] aligns Array of alignment requirements
Return values:
Value SALLD Function Return Codes
uint32_t Sa_chanGetID ( Sa_ChanHandle  handle  ) 

Sa_chanGetID returns the SA channel ID associated with the specified handle.

The function is called to request the SA channel ID corresponding to the handle.

Parameters:
[in] handle SALLD instance identifier.
Return values:
Channel ID
Precondition:
Sa_chanInit function should be called before calling this function
int16_t Sa_chanGetShadowHandle ( Sa_ChanHandle  handle,
Sa_ChanHandle shandle 
)

Sa_chanGetShadowHandle queries the shadow channel handle.

This function returns the shadow channel handle. The shadow channel handle is set to NULL if it does not exist. Refer to Shadow Instance for mixed-Endian operation for details

Parameters:
[in] handle The PA LLD channel instance identifier
[in] shandle Pointer to the shadow channel handle
Return values:
Value SALLD Function Return Codes
int16_t Sa_chanGetStats ( Sa_ChanHandle  handle,
uint16_t  flags,
Sa_Stats_t stats 
)

This function obtains SALLD channel protocol-specific statistics.

Parameters:
[in] handle SALLD channel instance identifier.
[in] flags Various control flags SALLD Statistics Query Control Bit Definitions
[in,out] stats Pointer to protocol-specific statistics
Return values:
Value SALLD Function Return Codes
int16_t Sa_chanGetSwInfo ( Sa_ChanHandle  handle,
uint16_t  dir,
Sa_SWInfo_t pChanSwInfo 
)

Sa_chanGetSwInfo returns the SA-specific software information required for all packets to be delivered to SA.

It is an optional utility function to query the SA-specific software information in both directions in case Sa_chanSendData() is not used and/or the callout function ChanRegister() is not implemented.

In normal operation, the from-network SWInfo will be passed to module user via callout function ChanRegister() and the to-network SWInfo will be passed to module user via API Sa_chanSendData().

Parameters:
[in] handle SALLD channel instance identifier.
[in] dir Packet direction as specified at Sa_PktDir_t
[in] pChanSwInfo Pointer to SALLD software routing information structure.
Return values:
Value SALLD Function Return Codes
See also:
Sa_SWInfo_t
int16_t Sa_chanReceiveData ( Sa_ChanHandle  handle,
Sa_PktInfo_t pktInfo 
)

This function processes packets received from the network. It performs protocol-specific post-SA operations on the decrypted and/or integrity-verified data packet. It also performs the actual decryption/authentication operation in SW-only mode.

Parameters:
[in] handle SALLD channel instance identifier.
[in] pktInfo Pointer to the packet info structure.
Return values:
Value SALLD Function Return Codes
See also:
Sa_PktInfo_t
int16_t Sa_chanSendData ( Sa_ChanHandle  handle,
Sa_PktInfo_t pktInfo,
uint16_t  clear 
)

This function processes the data packet to the networks. It performs protocol-specific operations to prepare the data packets to be encrypted and/or authenticated by the SA. It also performs the actual encryption and/or authentication in the SW-only mode.

Parameters:
[in] handle SALLD channel instance identifier.
[in] pktInfo Pointer to the packet info structure.
[in] clear Flag indicating whether to force non-encryption
Return values:
Value SALLD Function Return Codes
See also:
Sa_PktInfo_t
int16_t Sa_chanStart ( Sa_ChanHandle  handle  ) 

This function activates the local channel instance at other DSP cores. It should be called once at any other DSP cores which invoke the same SALLD channel that is created and configured at the master core. It is up to the master core to make the channel handle public and accessible by other DSP cores after channel creation and configuration. The following APIs are supported at slave cores.

  • Sa_chanReceiveData
  • Sa_chanSendData
  • Sa_chanGetStats
  • Sa_chanGetID.

Parameters:
[in] handle SALLD channel instance identifier.
Return values:
Value SALLD Function Return Codes
Note:
: This function should be called prior to other channel APIs such as Sa_chanSendData() and Sa_chanReceiveData() are invoked
int16_t Sa_close ( Sa_Handle  handle,
void *  bases[] 
)

Sa_close deactivates the SA LLD instance.

This function deactivates the SA LLD instance, all the associated memory buffers can be freed after this call.

Parameters:
[in] handle The PA LLD instance identifier
[out] bases Array of the memory buffer base addresses
Return values:
Value SALLD Function Return Codes
int16_t Sa_create ( Sa_Config_t cfg,
void *  bases[],
Sa_Handle pHandle 
)

Sa_create creates the SA LLD instance. It initializes the SALLD instance and its corresponding instance structure based on channel configuration data such as the call-out table, and etc.

Parameters:
[in] cfg Configuration information
[in] bases Array of the memory buffer base addresses
[out] pHandle Instance handle. This is a pointer to an initialized instance structure.
Return values:
Value SALLD Function Return Codes
See also:
Sa_Config_t
Note:
The system buffers should be allocated from global accessible memory blocks and global addresses should be used if the LLD instance is expected to be shared among multiple cores.
int16_t Sa_downloadImage ( Sa_Handle  handle,
int  modId,
void *  image,
int  sizeBytes 
)

This function downloads a PDSP image to a PDSP core within the SA sub-system.

This function is used to download an executable image to a packet processing module.

Parameters:
[in] handle SALLD instance identifier.
[in] modId The PDSP number (0-1)
[in] image The image to download
[in] sizeBytes The size of the image
Return values:
Value SALLD Function Return Codes
Precondition:
The packet processing modules must be in reset. See Sa_resetControl.
int16_t Sa_getBufferReq ( Sa_SizeCfg_t sizeCfg,
int  sizes[],
int  aligns[] 
)

Sa_getBufferReq returns the memory requirements for the SALLD instance.

This function returns the memory buffer requirements in terms of the size and alignment array. The SA LLD requires only one memory block as described below:

  • SA Instance: SA instance data
Parameters:
[in] sizeCfg Size configuration information
[out] sizes Array of size requirements
[out] aligns Array of alignment requirements
Return values:
Value SALLD Function Return Codes
See also:
Sa_SizeCfg_t
uint32_t Sa_getID ( Sa_Handle  handle  ) 

This function returns the SA system ID associated with the specified handle.

The function is called to request the SA system ID corresponding to the handle.

Parameters:
[in] handle SALLD instance identifier.
Return values:
SA system ID
Precondition:
Sa_create function should be called before calling this function
int16_t Sa_getPDSPVersion ( Sa_Handle  handle,
int  modId,
uint32_t *  pVersion 
)

Sa_getPDSPVersion returns the SA PDSP version information.

This function is used to get the SA PDSP version information in 0xAABBCCDD format. where Arch (AA); API Changes (BB); Major (CC); Minor (DD

Parameters:
[in] handle SALLD instance identifier.
[in] modId The PDSP number (0-1)
[out] pVersion The pointer to PDSP version number
Return values:
Value SALLD Function Return Codes
Precondition:
The PDSP image should be downloaded successfully.
int16_t Sa_getRandomNum ( Sa_Handle  handle,
uint16_t  f_isr,
Sa_RngData_t rnd 
)

This function returns a 64-bit true random number.

This function is called to get a 64-bit true random number. It is a non-blocking function call which indicates the random number is not available if the RNG is still in the process of generating the next random number.

Remarks:
For a multi-core device, it is up to the application to prevent this function from being invoked by multiple CGEM cores simultaneously.
Parameters:
[in] handle SALLD instance identifier.
[in] f_isr Flag to indicate whether it is called from interrupt srevice routine
[in] rnd Pointer to the 64-bit random number
Return values:
Value SALLD Function Return Codes
Precondition:
RNG is initialized
int16_t Sa_getShadowHandle ( Sa_Handle  handle,
Sa_Handle shandle 
)

Sa_getShadowHandle queries the shadow system handle.

This function returns the shadow system handle. The shadow system handle is set to NULL if it does not exist. Refer to Shadow Instance for mixed-Endian operation for details

Parameters:
[in] handle The PA LLD instance identifier
[in] shandle Pointer to the shadow system handle
Return values:
Value SALLD Function Return Codes
int16_t Sa_getSysStats ( Sa_Handle  handle,
Sa_SysStats_t stats 
)

This function obtains SALLD system statistics.

Parameters:
[in] handle SALLD instance identifier.
[in,out] stats pointer to system statistics
Return values:
Value SALLD Function Return Codes
uint32_t Sa_getVersion ( void   ) 

Sa_getVersion returns the SA LLD version information.

This function is used to get the version information of the SA LLD in 0xAABBCCDD format. where Arch (AA); API Changes (BB); Major (CC); Minor (DD)

Return values:
32-bit version information
const char* Sa_getVersionStr ( void   ) 

Sa_getVersionStr returns the SA LLD version string.

This function is used to get the version string of the SA LLD.

Return values:
Version string
uint16_t Sa_isScBufFree ( uint8_t *  scBuf  ) 

This function verifies whether the security context buffer has been freed by SA.

Parameters:
[in] scBuf Pointer to the Security Context buffer.
Return values:
TRUE if buffer is free; FALSE if otherwise
int16_t Sa_pkaClose ( Sa_Handle  handle  ) 

Sa_pkaClose decativates the SA PKA module.

This function deactivates the SA PKA module and clears LLD internal state.

Parameters:
[in] handle The PA LLD instance identifier
Return values:
Value SALLD Function Return Codes
int16_t Sa_pkaInit ( Sa_Handle  handle  ) 

This function initializes the PKA (Public Key Accelerator) module inside SA.

The function is called to initialize the PKA module inside SA.

Remarks:
For a multi-core device, it is up to the upper-layer application to make sure that only the master core performs the PKA hardware initialization.
Parameters:
[in] handle SALLD instance identifier.
Return values:
Value SALLD Function Return Codes
Precondition:
None
int16_t Sa_pkaOperation ( Sa_Handle  handle,
Sa_PkaReqInfo_t pkaReqInfo 
)

This function triggers a large vector arithmetic operation through the PKA module.

The function is called to perform a large vector arithmetic operation through the PKA module. It is considered as a blocking function call since it will wait for the PKA module to complete the arithmetic operation. However, it only takes a few cycles for PKA to complete any operation. This function also returns with error code immediately if the PKA is still in the process to perform the previous operation or when timeout occurs.

Remarks:
For a multi-core device, it is up to the application to prevent this function from being invoked by multiple CGEM cores simultaneously.
Parameters:
[in] handle SALLD instance identifier.
[in] pkaReqInfo Pointer to the PKA operation request information structure
Return values:
Value SALLD Function Return Codes
Precondition:
PKA is initialized
Sa_State_t Sa_resetControl ( Sa_Handle  handle,
Sa_State_t  newState 
)

This function controls the reset state of the SA Sub-System.

This function is used to assert or release reset for the sub-system. Asserting reset does not reset any of the sub-system internal data, but only the packet processing modules. To acheive a complete system reset the system-level reset must be asserted through the power controller.

Parameters:
[in] handle SALLD instance identifier.
[in] newState Value SALLD Sub-System Queries and States
Return values:
Value SALLD Sub-System Queries and States
Precondition:
None
int16_t Sa_rngClose ( Sa_Handle  handle  ) 

Sa_rngClose decativates the SA RNG module.

This function deactivates the SA RNG module and clears LLD internal state.

Parameters:
[in] handle The PA LLD instance identifier
Return values:
Value SALLD Function Return Codes
int16_t Sa_rngInit ( Sa_Handle  handle,
Sa_RngConfigParams_t cfg 
)

The function is called to initialize and configure the RNG (Random Number Generator) module inside SA.

Remarks:
For a multi-core device, it is up to the upper-layer application to make sure that only the master core performs the RNG hardware initialization.
Parameters:
[in] handle SALLD instance identifier.
[in] cfg Pointer the RNG configuration parameters as defined at Sa_RngConfigParams_t
Return values:
Value SALLD Function Return Codes
Precondition:
None
int16_t Sa_start ( Sa_Handle  handle,
Sa_Config_t cfg 
)

Sa_start activates the SA LLD instance.

This function activates the SA LLD instance. This function should be called once at all other DSP cores which share the same SALLD instance.

Parameters:
[in] handle The PA LLD instance identifier
[in] cfg Configuration information
Return values:
Value SALLD Function Return Codes
Note:
: It is optional to call the function at the DSP core where Sa_create() is invoked.

Copyright 2014, Texas Instruments Incorporated