Introduction

The SCIClient has two major functions:

Interact with DMSC ROM and load the DMSC Firmware.
Pass on service requests from higher level software to the DMSC firmware and forward the response from DMSC firmware to the higher level software.

The Sciclient_loadFirmware API is used to cater to the first requirement and the Sciclient_service is used to cater to the second. The SCIClient library requires initialization of the a handle which is used by the subsequent API calls. This handle is initialized by the Sciclient_init function. Once the application/higher level software is being torn down or exiting the Sciclient_deinit can be used to de-initialize this handle.

The SCIClient can operate in the following combinations:

Non-OS, Polling based message completion.
Non-OS, Interrupt Based message completion.
RTOS, Polling based message completion.
RTOS, Interrupt based message completion.

The SCIClient depends on the OSAL layer to differentiate between the Non-OS and the RTOS implementation of Semaphores and Interrupts (HWIs). The build parameter of the OSAL library would determine if the application is bare metal or RTOS based. The polling versus interrupt based wait for message completion is a run time configuration passed during the Sciclient_init initialization.

All the APIs for interacting with the firmware are blocking with a specified timeout . A common API Sciclient_service is implemented for all types of calls to the firmware which takes 2 arguments :

The API serves a particular request, based on the value of messageType parameter in Sciclient_ReqPrm_t, whose response is given to the higher level API through Sciclient_RespPrm_t. The Sciclient_ReqPrm_t contains the required inputs from the higher level software corresponding to the message_type, timeout value and the core message as a byte stream. A pointer Sciclient_RespPrm_t has to be passed to the sciclient, which shall be modified by sciclient.

The Sciclient shall be responsible for abstracting all interaction with the secure proxy and the ring accelerator.

Sub Modules
	Sciclient Interface to DMSC ROM

Files
file	sciclient.h
	This file contains prototypes for APIs contained as a part of SCICLIENT as well as the structures of their arguments.

Data Structures
struct	Sciclient_ConfigPrms_t
	Initialization parameters for sciclient. Pointer to this is passed to Sciclient_init. More...

struct	Sciclient_ReqPrm_t
	Input parameters for Sciclient_service function. More...

struct	Sciclient_RespPrm_t
	Output parameters for Sciclient_service function. More...

struct	Sciclient_DefaultBoardCfgInfo_t
	Input parameters for Sciclient_service function. More...

Functions
int32_t	Sciclient_loadFirmware (const uint32_t *pSciclient_firmware)
	Loads the DMSC firmware. This is typically called by SBL. Load firmware does not require calling the Sciclient_init function. More...

int32_t	Sciclient_init (const Sciclient_ConfigPrms_t *pCfgPrms)
	This API is called once for registering interrupts and creating semaphore handles to be able to talk to the firmware. The application should assume that the firmware is pre-loaded while calling the Sciclient_init API. The firmware should have been loaded either via GEL or via the SBL prior to the application calling the Sciclient_init. If a void pointer is passed, default values will be used, else the values passed will be used. Only first Sciclient_init call configuration will take effect, subsequent calls will return pass witout overwriting the previous configuration. More...

int32_t	Sciclient_service (const Sciclient_ReqPrm_t pReqPrm, Sciclient_RespPrm_t pRespPrm)
	This API allows communicating with the System firmware which can be called to perform various functions in the system. Core sciclient function for transmitting payload and recieving the response. The caller is expected to allocate memory for the input request parameter (Refer Sciclient_ReqPrm_t). This involves setting the message type being communicated to the firmware, the response flags, populate the payload of the message based on the inputs in the files sciclient_fmwPmMessages.h,sciclient_fmwRmMessages.h, sciclient_fmwSecMessages.h and sciclient_fmwCommonMessages.h. Since the payload in considered a stream of bytes in this API, the caller should also populate the size of this stream in reqPayloadSize. The timeout is used to determine for what amount of iterations the API would wait for their operation to complete. More...

int32_t	Sciclient_deinit (void)
	De-initialization of sciclient. This de-initialization is specific to the application. It only de-initializes the semaphores, interrupts etc. which are initialized in Sciclient_init. It does not de-initialize the system firmware. More...

int32_t	Sciclient_abiCheck (void)

int32_t	Sciclient_getDefaultBoardCfgInfo (Sciclient_DefaultBoardCfgInfo_t *pBoardCfgInfo)
	API to get the default board config info. More...

int32_t	Sciclient_configPrmsInit (Sciclient_ConfigPrms_t *pCfgPrms)
	Sciclient_ConfigPrms_t structure init function. More...

void	Sciclient_TisciMsgSetAckResp (struct tisci_header *hdr)
	Send the Response in Ack. Used only with Sciserver or Sciclient Direct. More...

void	Sciclient_TisciMsgSetNakResp (struct tisci_header *hdr)
	Send the Response in NAK. Used only with Sciserver or Sciclient Direct. More...

int32_t	Sciclient_boardCfgPrepHeader (uint8_t pCommonHeader, uint8_t pBoardCfgHeader, const Sciclient_BoardCfgPrms_t pInPmPrms, const Sciclient_BoardCfgPrms_t pInRmPrms)
	Prepare the header for the board configuration. This API is typically only used by SBL where it will prepare the headers for the sciserver to come and then read the board configurations for PM and RM. This will set up the headers which Sciserver will look to read the board configuration which the SBL leaves behind after boot. The Sciserver app will then send the configs for board configuration based on this. More...

int32_t	Sciclient_boardCfgParseHeader (uint8_t pCommonHeader, Sciclient_BoardCfgPrms_t pInPmPrms, Sciclient_BoardCfgPrms_t *pInRmPrms)
	Parse the header left behind by the SBL in the SCISERVER. This is used in the SCISERVER App to read the left behind header and configuration paramter. More...

Typedefs
typedef uint8_t	domgrp_t
	Defines the sysfw DOMGRP type. This is meant to be used in code or data structures that require distinction of domgrps. More...

typedef uint8_t	devgrp_t
	Defines the sysfw DEVGRP type. This is meant to be used in code or data structures that require distinction of devgrps. More...

Macros
#define	TISCI_BIT(n) (1UL << (n))

#define	DEVGRP_ALL (0x00U)

#define	DEVGRP_00 ((0x01U) << 0U)

#define	DEVGRP_01 ((0x01U) << 1U)

#define	DEVGRP_02 ((0x01U) << 2U)

#define	DEVGRP_03 ((0x01U) << 3U)

#define	DEVGRP_04 ((0x01U) << 4U)

#define	DEVGRP_05 ((0x01U) << 5U)

#define	DEVGRP_06 ((0x01U) << 6U)

#define	DEVGRP_DMSC ((0x01U) << 7U)

#define	DEVGRP_DMSC_ALL (0xFFU)

#define	SCICLIENT_COMMON_X509_HEADER_ADDR (0x41cffb00)

#define	SCISERVER_COMMON_X509_HEADER_ADDR SCICLIENT_COMMON_X509_HEADER_ADDR

#define	MAX_NUM_DEVGRPS (8U)

#define	SCICLIENT_FT_PASS (0xA5A5U)

#define	SCICLIENT_FT_FAIL (0x5A5AU)

Sciclient Service API Operation Mode
Sciclient Service API Operation Mode. The different types of modes supported are: (1) Polled Mode : no interrupts are registered. The completion of a message is via polling on the Proxy registers. (2) Interrupt Mode : Interrupt are registered and the response message would be via a interrupt routine. Default mode in case Sciclient_ConfigPrms_t is NULL is interrupt.
#define	SCICLIENT_SERVICE_OPERATION_MODE_POLLED (0U)

#define	SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT (1U)

Sciclient Service API Operation Timeout
Sciclient Service API Timeout Values. The different types are: (1) Wait forever for an operation to complete. (2) Do not wait for the operation to complete. (3) Wait for a given time interface for the operation to complete.
#define	SCICLIENT_SERVICE_WAIT_FOREVER (0xFFFFFFFFU)

#define	SCICLIENT_SERVICE_NO_WAIT (0x0U)

Macro Definition Documentation

◆ TISCI_BIT

#define TISCI_BIT ( n ) (1UL << (n))

◆ DEVGRP_ALL

#define DEVGRP_ALL (0x00U)

SoC SYSFW devgrp any: NOT TO BE used for SoC data. This implies that specific sequenced devgrp is NOT used

◆ DEVGRP_00

#define DEVGRP_00 ((0x01U) << 0U)

SoC defined SYSFW devgrp 00

◆ DEVGRP_01

#define DEVGRP_01 ((0x01U) << 1U)

SoC defined SYSFW devgrp 01

◆ DEVGRP_02

#define DEVGRP_02 ((0x01U) << 2U)

SoC defined SYSFW devgrp 02

◆ DEVGRP_03

#define DEVGRP_03 ((0x01U) << 3U)

SoC defined SYSFW devgrp 03

◆ DEVGRP_04

#define DEVGRP_04 ((0x01U) << 4U)

SoC defined SYSFW devgrp 04

◆ DEVGRP_05

#define DEVGRP_05 ((0x01U) << 5U)

SoC defined SYSFW devgrp 05

◆ DEVGRP_06

#define DEVGRP_06 ((0x01U) << 6U)

SoC defined SYSFW devgrp 06

◆ DEVGRP_DMSC

#define DEVGRP_DMSC ((0x01U) << 7U)

SYSFW internal usage ONLY Module belonging solely to DMSC operations

◆ DEVGRP_DMSC_ALL

#define DEVGRP_DMSC_ALL (0xFFU)

Match everything - STRICTLY INTERNAL USAGE ONLY

◆ SCICLIENT_COMMON_X509_HEADER_ADDR

#define SCICLIENT_COMMON_X509_HEADER_ADDR (0x41cffb00)

Aligned address at which the X509 header is placed.

◆ SCISERVER_COMMON_X509_HEADER_ADDR

#define SCISERVER_COMMON_X509_HEADER_ADDR SCICLIENT_COMMON_X509_HEADER_ADDR

◆ MAX_NUM_DEVGRPS

#define MAX_NUM_DEVGRPS (8U)

Maximum number of devgrps that are supported by SYSFW. Derived from the above definitions

◆ SCICLIENT_SERVICE_OPERATION_MODE_POLLED

#define SCICLIENT_SERVICE_OPERATION_MODE_POLLED (0U)

◆ SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT

#define SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT (1U)

◆ SCICLIENT_SERVICE_WAIT_FOREVER

#define SCICLIENT_SERVICE_WAIT_FOREVER (0xFFFFFFFFU)

◆ SCICLIENT_SERVICE_NO_WAIT

#define SCICLIENT_SERVICE_NO_WAIT (0x0U)

◆ SCICLIENT_FT_PASS

#define SCICLIENT_FT_PASS (0xA5A5U)

Fault tolerant Pass

◆ SCICLIENT_FT_FAIL

#define SCICLIENT_FT_FAIL (0x5A5AU)

Fault tolerant Fail

Typedef Documentation

◆ domgrp_t

typedef uint8_t domgrp_t

Defines the sysfw DOMGRP type. This is meant to be used in code or data structures that require distinction of domgrps.

◆ devgrp_t

typedef uint8_t devgrp_t

Defines the sysfw DEVGRP type. This is meant to be used in code or data structures that require distinction of devgrps.

Function Documentation

◆ Sciclient_loadFirmware()

int32_t Sciclient_loadFirmware ( const uint32_t * pSciclient_firmware )

Loads the DMSC firmware. This is typically called by SBL. Load firmware does not require calling the Sciclient_init function.

Requirement: DOX_REQ_TAG(PDK-2137), DOX_REQ_TAG(PDK-2138)

Parameters

pSciclient_firmware [IN] Pointer to signed SYSFW binary

Returns: CSL_PASS on success, else failure

◆ Sciclient_init()

int32_t Sciclient_init ( const Sciclient_ConfigPrms_t * pCfgPrms )

This API is called once for registering interrupts and creating semaphore handles to be able to talk to the firmware. The application should assume that the firmware is pre-loaded while calling the Sciclient_init API. The firmware should have been loaded either via GEL or via the SBL prior to the application calling the Sciclient_init. If a void pointer is passed, default values will be used, else the values passed will be used. Only first Sciclient_init call configuration will take effect, subsequent calls will return pass witout overwriting the previous configuration.

Requirement: DOX_REQ_TAG(PDK-2146)

Parameters

pCfgPrms [IN] Pointer to Sciclient_ConfigPrms_t

Returns: CSL_PASS on success, else failure

◆ Sciclient_service()

int32_t Sciclient_service	(	const Sciclient_ReqPrm_t *	pReqPrm,
		Sciclient_RespPrm_t *	pRespPrm
	)

This API allows communicating with the System firmware which can be called to perform various functions in the system. Core sciclient function for transmitting payload and recieving the response. The caller is expected to allocate memory for the input request parameter (Refer Sciclient_ReqPrm_t). This involves setting the message type being communicated to the firmware, the response flags, populate the payload of the message based on the inputs in the files sciclient_fmwPmMessages.h,sciclient_fmwRmMessages.h, sciclient_fmwSecMessages.h and sciclient_fmwCommonMessages.h. Since the payload in considered a stream of bytes in this API, the caller should also populate the size of this stream in reqPayloadSize. The timeout is used to determine for what amount of iterations the API would wait for their operation to complete.

To make sure the response is captured correctly the caller should also allocate the space for Sciclient_RespPrm_t parameters. The caller should populate the pointer to the pRespPayload and the size respPayloadSize. The API would populate the response flags to indicate any firmware specific errors and also populate the memory pointed by pRespPayload till the size given in respPayloadSize.

Requirement: DOX_REQ_TAG(PDK-2142), DOX_REQ_TAG(PDK-2141), DOX_REQ_TAG(PDK-2140), DOX_REQ_TAG(PDK-2139)

Parameters

pReqPrm	[IN] Pointer to Sciclient_ReqPrm_t
pRespPrm	[OUT] Pointer to Sciclient_RespPrm_t

Returns: CSL_PASS on success, else failure

◆ Sciclient_deinit()

int32_t Sciclient_deinit ( void )

De-initialization of sciclient. This de-initialization is specific to the application. It only de-initializes the semaphores, interrupts etc. which are initialized in Sciclient_init. It does not de-initialize the system firmware.

Requirement: DOX_REQ_TAG(PDK-2146)

Returns: CSL_PASS on success, else failureAPI to verify that firmware ABI matches the supported ABI.; CSL_PASS on success, else failure

◆ Sciclient_abiCheck()

int32_t Sciclient_abiCheck ( void )

◆ Sciclient_getDefaultBoardCfgInfo()

int32_t Sciclient_getDefaultBoardCfgInfo ( Sciclient_DefaultBoardCfgInfo_t * pBoardCfgInfo )

API to get the default board config info.

Returns: CSL_PASS on success, else failure

◆ Sciclient_configPrmsInit()

int32_t Sciclient_configPrmsInit ( Sciclient_ConfigPrms_t * pCfgPrms )

Sciclient_ConfigPrms_t structure init function.

Parameters

pCfgPrms [IN] Pointer to Sciclient_ConfigPrms_t structure.

◆ Sciclient_TisciMsgSetAckResp()

void Sciclient_TisciMsgSetAckResp ( struct tisci_header * hdr )

Send the Response in Ack. Used only with Sciserver or Sciclient Direct.

Parameters

hdr	[IN] Pointer to tisci_header structure.

◆ Sciclient_TisciMsgSetNakResp()

void Sciclient_TisciMsgSetNakResp ( struct tisci_header * hdr )

Send the Response in NAK. Used only with Sciserver or Sciclient Direct.

Parameters

hdr	[IN] Pointer to tisci_header structure.

◆ Sciclient_boardCfgPrepHeader()

int32_t Sciclient_boardCfgPrepHeader	(	uint8_t *	pCommonHeader,
		uint8_t *	pBoardCfgHeader,
		const Sciclient_BoardCfgPrms_t *	pInPmPrms,
		const Sciclient_BoardCfgPrms_t *	pInRmPrms
	)

Prepare the header for the board configuration. This API is typically only used by SBL where it will prepare the headers for the sciserver to come and then read the board configurations for PM and RM. This will set up the headers which Sciserver will look to read the board configuration which the SBL leaves behind after boot. The Sciserver app will then send the configs for board configuration based on this.

Parameters

pCommonHeader	Pointer to the common header which corresponds to the format for the component left behind.
pBoardCfgHeader	Pointer to the board configuration header which corresponds to the table which defines the board config params.
pInPmPrms	Pointer to the PM parameters.
pInRmPrms	Pointer to the RM parameters.

Returns: ret CSL_PASS if the paramters are populated correctly in the header. Fail otherwise.

◆ Sciclient_boardCfgParseHeader()

int32_t Sciclient_boardCfgParseHeader	(	uint8_t *	pCommonHeader,
		Sciclient_BoardCfgPrms_t *	pInPmPrms,
		Sciclient_BoardCfgPrms_t *	pInRmPrms
	)

Parse the header left behind by the SBL in the SCISERVER. This is used in the SCISERVER App to read the left behind header and configuration paramter.

Parameters

pCommonHeader	Pointer to the common header which corresponds to the format for the component left behind.
pInPmPrms	Pointer to the PM parameters popolated by the API.
pInRmPrms	Pointer to the RM parameters popolated by the API.

Returns: ret CSL_PASS if the paramters are populated correctly. Fail otherwise.

Introduction

Sub Modules

Files

Data Structures

Functions

Typedefs

Macros

Sciclient Service API Operation Mode

Sciclient Service API Operation Timeout

Macro Definition Documentation

◆ TISCI_BIT

◆ DEVGRP_ALL

◆ DEVGRP_00

◆ DEVGRP_01

◆ DEVGRP_02

◆ DEVGRP_03

◆ DEVGRP_04

◆ DEVGRP_05

◆ DEVGRP_06

◆ DEVGRP_DMSC

◆ DEVGRP_DMSC_ALL

◆ SCICLIENT_COMMON_X509_HEADER_ADDR

◆ SCISERVER_COMMON_X509_HEADER_ADDR

◆ MAX_NUM_DEVGRPS

◆ SCICLIENT_SERVICE_OPERATION_MODE_POLLED

◆ SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT

◆ SCICLIENT_SERVICE_WAIT_FOREVER

◆ SCICLIENT_SERVICE_NO_WAIT

◆ SCICLIENT_FT_PASS

◆ SCICLIENT_FT_FAIL

Typedef Documentation

◆ domgrp_t

◆ devgrp_t

Function Documentation

◆ Sciclient_loadFirmware()

◆ Sciclient_init()

◆ Sciclient_service()

◆ Sciclient_deinit()

◆ Sciclient_abiCheck()

◆ Sciclient_getDefaultBoardCfgInfo()

◆ Sciclient_configPrmsInit()

◆ Sciclient_TisciMsgSetAckResp()

◆ Sciclient_TisciMsgSetNakResp()

◆ Sciclient_boardCfgPrepHeader()

◆ Sciclient_boardCfgParseHeader()