sip_svc.h File Reference

Public API for ARM SiP services. More...

#include <zephyr/kernel.h>
#include <zephyr/arch/arm64/arm-smccc.h>
#include <zephyr/drivers/sip_svc/sip_svc_proto.h>

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_token	Client's token
res	pointer 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

ctrl	Pointer to controller instance which provides ARM SiP services.
c_token	Client's token
pre_close_req	pre close request sent to lower layer on channel close.

Return values

0	on success, negative errno on failure.
-EINVAL	invalid arguments.
-ENOTSUP	error on sending pre_close_request.
-EPROTO	client is not in OPEN state.

sip_svc_get_controller()

void * sip_svc_get_controller

(

char *

method

)

get the ARM SiP service handle

Parameters

method

Pointer to controller instance which provides ARM SiP service.

Return values

Valid	pointer.
NULL	invalid 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

ctrl	Pointer to controller instance which provides ARM SiP service.
c_token	Client's token

Return values

Address	pointer to the client private data.
NULL	invalid 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

ctrl	Pointer to controller instance which provides ARM SiP services.
c_token	Client's token
k_timeout	Waiting 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

0	on success.
-EINVAL	invalid arguments.
-ETIMEDOUT	timeout expiry.
-EALREADY	client 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

ctrl	Pointer to controller instance whose service provides ARM SMC/HVC SiP services.
priv_data	Pointer to client private data.

Return values

token_id	on success.
SIP_SVC_ID_INVALID	invalid 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

ctrl	Pointer to controller instance which provides ARM SiP services.
c_token	Client's token
req	Address to the user input in struct sip_svc_request format.
cb	Callback. SMC/SVC return value will be passed to client via context in struct sip_svc_response format in callback.

Return values

transaction	id on success.
-EINVAL	invalid arguments.
-EOPNOTSUPP	invalid command id or function id.
-ESRCH	invalid client state.
-ENOMEM	failure to allocate memory.
-ENOMSG	failure to insert into database.
-ENOBUF	failure to insert into msgq.
-ENOLCK	failure to get lock.
-EHOSTDOWN	sip_svc thread not present.
-ENOTSUP	check 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

ctrl	Pointer to controller instance which provides ARM SiP services.
c_token	Client's token

Return values

0	on success.
-EINVALinvalid	arguments.
-ENODATA	if client is not registered correctly.
-EBUSY	if client has pending transactions.
-ECANCELED	if client is not in IDLE state.
-ENOLCK	if failure in acquiring mutex.