Line data Source code
1 1 : /*
2 : * Copyright (c) 2022-2023, Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_SIP_SVC_H_
8 : #define ZEPHYR_INCLUDE_SIP_SVC_H_
9 :
10 : /**
11 : * @file
12 : * @brief Public API for ARM SiP services
13 : *
14 : * ARM SiP service provides the capability to send the
15 : * SMC/HVC call from kernel running at EL1 to hypervisor/secure
16 : * monitor firmware running at EL2/EL3.
17 : *
18 : * Only allow one SMC and one HVC per system.
19 : *
20 : * The service support multiple clients.
21 : *
22 : * The client must open a channel before sending any request and
23 : * close the channel immediately after complete. The service only
24 : * allow one channel at one time.
25 : *
26 : * The service will return the SMC/HVC return value to the client
27 : * via callback function.
28 : *
29 : * The client state machine
30 : * - INVALID: Invalid state before registration.
31 : * - IDLE : Initial state.
32 : * - OPEN : The client will switch from IDLE to OPEN once it
33 : * successfully open the channel. On the other hand, it
34 : * will switch from OPEN to IDLE state once it successfully
35 : * close the channel.
36 : * - ABORT : The client has closed the channel, however, there are
37 : * incomplete transactions being left over. The service
38 : * will only move the client back to IDLE state once all
39 : * transactions completed. The client is not allowed to
40 : * re-open the channel when in ABORT state/
41 : */
42 :
43 : #include <zephyr/kernel.h>
44 : #include <zephyr/arch/arm64/arm-smccc.h>
45 : #include <zephyr/drivers/sip_svc/sip_svc_proto.h>
46 :
47 0 : #define SIP_SVC_CLIENT_ST_INVALID 0
48 0 : #define SIP_SVC_CLIENT_ST_IDLE 1
49 0 : #define SIP_SVC_CLIENT_ST_OPEN 2
50 0 : #define SIP_SVC_CLIENT_ST_ABORT 3
51 :
52 : /** @brief ARM sip service callback function prototype for response after completion
53 : *
54 : * On success , response is returned via a callback to the user.
55 : *
56 : * @param c_token Client's token
57 : * @param res pointer to struct sip_svc_response
58 : */
59 1 : typedef void (*sip_svc_cb_fn)(uint32_t c_token, struct sip_svc_response *res);
60 :
61 : /**
62 : * @brief Register a client on ARM SiP service
63 : *
64 : * On success, the client will be at IDLE state in the service and
65 : * the service will return a token to the client. The client can then
66 : * use the token to open the channel on the service and communicate
67 : * with hypervisor/secure monitor firmware running at EL2/EL3.
68 : *
69 : * @param ctrl Pointer to controller instance whose service provides ARM SMC/HVC
70 : * SiP services.
71 : * @param priv_data Pointer to client private data.
72 : *
73 : * @retval token_id on success.
74 : * @retval SIP_SVC_ID_INVALID invalid arguments, failure to allocate a client id and failure to get
75 : * a lock.
76 : */
77 1 : uint32_t sip_svc_register(void *ctrl, void *priv_data);
78 :
79 : /**
80 : * @brief Unregister a client on ARM SiP service
81 : *
82 : * On success, detach the client from the service. Unregistration
83 : * is only allowed when all transactions belong to the client are closed.
84 : *
85 : * @param ctrl Pointer to controller instance which provides ARM SiP services.
86 : * @param c_token Client's token
87 : *
88 : * @retval 0 on success.
89 : * @retval -EINVALinvalid arguments.
90 : * @retval -ENODATA if client is not registered correctly.
91 : * @retval -EBUSY if client has pending transactions.
92 : * @retval -ECANCELED if client is not in IDLE state.
93 : * @retval -ENOLCK if failure in acquiring mutex.
94 : */
95 1 : int sip_svc_unregister(void *ctrl, uint32_t c_token);
96 :
97 : /**
98 : * @brief Client requests to open a channel on ARM SiP service.
99 : *
100 : * Client must open a channel before sending any request via
101 : * SMC/HVC to hypervisor/secure monitor firmware running at EL2/EL3.
102 : *
103 : * The service only allows one opened channel at one time and it is protected
104 : * by mutex.
105 : *
106 : * @param ctrl Pointer to controller instance which provides ARM SiP services.
107 : * @param c_token Client's token
108 : * @param k_timeout Waiting time if the mutex have been locked.
109 : * When the mutex have been locked:
110 : * - returns non-zero error code immediately if value is K_NO_WAIT
111 : * - wait forever if the value is K_FOREVER
112 : * - otherwise, for the given time
113 : *
114 : * @retval 0 on success.
115 : * @retval -EINVAL invalid arguments.
116 : * @retval -ETIMEDOUT timeout expiry.
117 : * @retval -EALREADY client state is already open.
118 : */
119 1 : int sip_svc_open(void *ctrl, uint32_t c_token, k_timeout_t k_timeout);
120 :
121 : /**
122 : * @brief Client requests to close the channel on ARM SiP services.
123 : *
124 : * Client must close the channel immediately once complete.
125 : *
126 : * @param ctrl Pointer to controller instance which provides ARM SiP services.
127 : * @param c_token Client's token
128 : * @param pre_close_req pre close request sent to lower layer on channel close.
129 : *
130 : * @retval 0 on success, negative errno on failure.
131 : * @retval -EINVAL invalid arguments.
132 : * @retval -ENOTSUP error on sending pre_close_request.
133 : * @retval -EPROTO client is not in OPEN state.
134 : */
135 1 : int sip_svc_close(void *ctrl, uint32_t c_token, struct sip_svc_request *pre_close_req);
136 :
137 : /**
138 : * @brief Client requests to send a SMC/HVC call to EL3/EL2
139 : *
140 : * Client must open a channel on the device before using this function.
141 : * This function is non-blocking and can be called from any context. The
142 : * service will return a Transaction ID to the client if the request
143 : * is being accepted. Client callback is called when the transaction is
144 : * completed.
145 : *
146 : * @param ctrl Pointer to controller instance which provides ARM SiP services.
147 : * @param c_token Client's token
148 : * @param req Address to the user input in struct sip_svc_request format.
149 : * @param cb Callback. SMC/SVC return value will be passed to client via
150 : * context in struct sip_svc_response format in callback.
151 : *
152 : * @retval transaction id on success.
153 : * @retval -EINVAL invalid arguments.
154 : * @retval -EOPNOTSUPP invalid command id or function id.
155 : * @retval -ESRCH invalid client state.
156 : * @retval -ENOMEM failure to allocate memory.
157 : * @retval -ENOMSG failure to insert into database.
158 : * @retval -ENOBUF failure to insert into msgq.
159 : * @retval -ENOLCK failure to get lock.
160 : * @retval -EHOSTDOWN sip_svc thread not present.
161 : * @retval -ENOTSUP check for unsupported condition.
162 : */
163 1 : int sip_svc_send(void *ctrl, uint32_t c_token, struct sip_svc_request *req, sip_svc_cb_fn cb);
164 :
165 : /**
166 : * @brief Get the address pointer to the client private data.
167 : *
168 : * The pointer is provided by client during registration.
169 : *
170 : * @param ctrl Pointer to controller instance which provides ARM SiP service.
171 : * @param c_token Client's token
172 : *
173 : * @retval Address pointer to the client private data.
174 : * @retval NULL invalid arguments and failure to get lock.
175 : */
176 1 : void *sip_svc_get_priv_data(void *ctrl, uint32_t c_token);
177 :
178 : /**
179 : * @brief get the ARM SiP service handle
180 : *
181 : * @param method Pointer to controller instance which provides ARM SiP service.
182 : *
183 : * @retval Valid pointer.
184 : * @retval NULL invalid arguments and on providing unsupported method name.
185 : */
186 1 : void *sip_svc_get_controller(char *method);
187 :
188 : #endif /* ZEPHYR_INCLUDE_SIP_SVC_H_ */
|
