Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
sip_svc.h File Reference

Public API for ARM SiP services. More...

Go to the source code of this file.

Macros

#define SIP_SVC_CLIENT_ST_INVALID   0
 
#define SIP_SVC_CLIENT_ST_IDLE   1
 
#define SIP_SVC_CLIENT_ST_OPEN   2
 
#define SIP_SVC_CLIENT_ST_ABORT   3
 

Typedefs

typedef void(* sip_svc_cb_fn) (uint32_t c_token, struct sip_svc_response *res)
 ARM sip service callback function prototype for response after completion.
 

Functions

uint32_t sip_svc_register (void *ctrl, void *priv_data)
 Register a client on ARM SiP service.
 
int sip_svc_unregister (void *ctrl, uint32_t c_token)
 Unregister a client on ARM SiP service.
 
int sip_svc_open (void *ctrl, uint32_t c_token, k_timeout_t k_timeout)
 Client requests to open a channel on ARM SiP service.
 
int sip_svc_close (void *ctrl, uint32_t c_token, struct sip_svc_request *pre_close_req)
 Client requests to close the channel on ARM SiP services.
 
int sip_svc_send (void *ctrl, uint32_t c_token, struct sip_svc_request *req, sip_svc_cb_fn cb)
 Client requests to send a SMC/HVC call to EL3/EL2.
 
void * sip_svc_get_priv_data (void *ctrl, uint32_t c_token)
 Get the address pointer to the client private data.
 
void * sip_svc_get_controller (char *method)
 get the ARM SiP service handle
 

Detailed Description

Public API for ARM SiP services.

ARM SiP service provides the capability to send the SMC/HVC call from kernel running at EL1 to hypervisor/secure monitor firmware running at EL2/EL3.

Only allow one SMC and one HVC per system.

The service support multiple clients.

The client must open a channel before sending any request and close the channel immediately after complete. The service only allow one channel at one time.

The service will return the SMC/HVC return value to the client via callback function.

The client state machine

  • INVALID: Invalid state before registration.
  • IDLE : Initial state.
  • OPEN : The client will switch from IDLE to OPEN once it successfully open the channel. On the other hand, it will switch from OPEN to IDLE state once it successfully close the channel.
  • ABORT : The client has closed the channel, however, there are incomplete transactions being left over. The service will only move the client back to IDLE state once all transactions completed. The client is not allowed to re-open the channel when in ABORT state/

Macro Definition Documentation

◆ SIP_SVC_CLIENT_ST_ABORT

#define SIP_SVC_CLIENT_ST_ABORT   3

◆ SIP_SVC_CLIENT_ST_IDLE

#define SIP_SVC_CLIENT_ST_IDLE   1

◆ SIP_SVC_CLIENT_ST_INVALID

#define SIP_SVC_CLIENT_ST_INVALID   0

◆ SIP_SVC_CLIENT_ST_OPEN

#define SIP_SVC_CLIENT_ST_OPEN   2

Typedef Documentation

◆ sip_svc_cb_fn

typedef void(* sip_svc_cb_fn) (uint32_t c_token, struct sip_svc_response *res)

ARM sip service callback function prototype for response after completion.

On success , response is returned via a callback to the user.

Parameters
c_tokenClient's token
respointer to struct sip_svc_response

Function Documentation

◆ sip_svc_close()

int sip_svc_close ( void *  ctrl,
uint32_t  c_token,
struct sip_svc_request pre_close_req 
)

Client requests to close the channel on ARM SiP services.

Client must close the channel immediately once complete.

Parameters
ctrlPointer to controller instance which provides ARM SiP services.
c_tokenClient's token
pre_close_reqpre close request sent to lower layer on channel close.
Return values
0on success, negative errno on failure.
-EINVALinvalid arguments.
-ENOTSUPerror on sending pre_close_request.
-EPROTOclient is not in OPEN state.

◆ sip_svc_get_controller()

void * sip_svc_get_controller ( char *  method)

get the ARM SiP service handle

Parameters
methodPointer to controller instance which provides ARM SiP service.
Return values
Validpointer.
NULLinvalid arguments and on providing unsupported method name.

◆ sip_svc_get_priv_data()

void * sip_svc_get_priv_data ( void *  ctrl,
uint32_t  c_token 
)

Get the address pointer to the client private data.

The pointer is provided by client during registration.

Parameters
ctrlPointer to controller instance which provides ARM SiP service.
c_tokenClient's token
Return values
Addresspointer to the client private data.
NULLinvalid arguments and failure to get lock.

◆ sip_svc_open()

int sip_svc_open ( void *  ctrl,
uint32_t  c_token,
k_timeout_t  k_timeout 
)

Client requests to open a channel on ARM SiP service.

Client must open a channel before sending any request via SMC/HVC to hypervisor/secure monitor firmware running at EL2/EL3.

The service only allows one opened channel at one time and it is protected by mutex.

Parameters
ctrlPointer to controller instance which provides ARM SiP services.
c_tokenClient's token
k_timeoutWaiting time if the mutex have been locked. When the mutex have been locked:
  • returns non-zero error code immediately if value is K_NO_WAIT
  • wait forever if the value is K_FOREVER
  • otherwise, for the given time
Return values
0on success.
-EINVALinvalid arguments.
-ETIMEDOUTtimeout expiry.
-EALREADYclient state is already open.

◆ sip_svc_register()

uint32_t sip_svc_register ( void *  ctrl,
void *  priv_data 
)

Register a client on ARM SiP service.

On success, the client will be at IDLE state in the service and the service will return a token to the client. The client can then use the token to open the channel on the service and communicate with hypervisor/secure monitor firmware running at EL2/EL3.

Parameters
ctrlPointer to controller instance whose service provides ARM SMC/HVC SiP services.
priv_dataPointer to client private data.
Return values
token_idon success.
SIP_SVC_ID_INVALIDinvalid arguments, failure to allocate a client id and failure to get a lock.

◆ sip_svc_send()

int sip_svc_send ( void *  ctrl,
uint32_t  c_token,
struct sip_svc_request req,
sip_svc_cb_fn  cb 
)

Client requests to send a SMC/HVC call to EL3/EL2.

Client must open a channel on the device before using this function. This function is non-blocking and can be called from any context. The service will return a Transaction ID to the client if the request is being accepted. Client callback is called when the transaction is completed.

Parameters
ctrlPointer to controller instance which provides ARM SiP services.
c_tokenClient's token
reqAddress to the user input in struct sip_svc_request format.
cbCallback. SMC/SVC return value will be passed to client via context in struct sip_svc_response format in callback.
Return values
transactionid on success.
-EINVALinvalid arguments.
-EOPNOTSUPPinvalid command id or function id.
-ESRCHinvalid client state.
-ENOMEMfailure to allocate memory.
-ENOMSGfailure to insert into database.
-ENOBUFfailure to insert into msgq.
-ENOLCKfailure to get lock.
-EHOSTDOWNsip_svc thread not present.
-ENOTSUPcheck for unsupported condition.

◆ sip_svc_unregister()

int sip_svc_unregister ( void *  ctrl,
uint32_t  c_token 
)

Unregister a client on ARM SiP service.

On success, detach the client from the service. Unregistration is only allowed when all transactions belong to the client are closed.

Parameters
ctrlPointer to controller instance which provides ARM SiP services.
c_tokenClient's token
Return values
0on success.
-EINVALinvalidarguments.
-ENODATAif client is not registered correctly.
-EBUSYif client has pending transactions.
-ECANCELEDif client is not in IDLE state.
-ENOLCKif failure in acquiring mutex.