1 /*
2 * Copyright (c) 2018-2021, Arm Limited. All rights reserved.
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7 #if SPMC_AT_EL3
8
9 #ifndef FFA_HELPERS_H
10 #define FFA_HELPERS_H
11
12 #include <stdint.h>
13 #include <services/ffa_svc.h>
14 #include "tsp_private.h"
15
16
17 typedef unsigned short ffa_id_t;
18 typedef uint64_t ffa_memory_handle_t;
19 /** Flags to indicate properties of receivers during memory region retrieval. */
20 typedef uint8_t ffa_memory_receiver_flags_t;
21
22 struct ffa_uuid {
23 const uint32_t uuid[4];
24 };
25
ffa_func_id(tsp_args_t val)26 static inline uint32_t ffa_func_id(tsp_args_t val) {
27 return (uint32_t) val._regs[0];
28 }
29
ffa_error_code(tsp_args_t val)30 static inline int32_t ffa_error_code(tsp_args_t val) {
31 return (uint32_t) val._regs[2];
32 }
33
34 enum ffa_data_access {
35 FFA_DATA_ACCESS_NOT_SPECIFIED,
36 FFA_DATA_ACCESS_RO,
37 FFA_DATA_ACCESS_RW,
38 FFA_DATA_ACCESS_RESERVED,
39 };
40
41 enum ffa_instruction_access {
42 FFA_INSTRUCTION_ACCESS_NOT_SPECIFIED,
43 FFA_INSTRUCTION_ACCESS_NX,
44 FFA_INSTRUCTION_ACCESS_X,
45 FFA_INSTRUCTION_ACCESS_RESERVED,
46 };
47
48 enum ffa_memory_type {
49 FFA_MEMORY_NOT_SPECIFIED_MEM,
50 FFA_MEMORY_DEVICE_MEM,
51 FFA_MEMORY_NORMAL_MEM,
52 };
53
54 enum ffa_memory_cacheability {
55 FFA_MEMORY_CACHE_RESERVED = 0x0,
56 FFA_MEMORY_CACHE_NON_CACHEABLE = 0x1,
57 FFA_MEMORY_CACHE_RESERVED_1 = 0x2,
58 FFA_MEMORY_CACHE_WRITE_BACK = 0x3,
59 FFA_MEMORY_DEV_NGNRNE = 0x0,
60 FFA_MEMORY_DEV_NGNRE = 0x1,
61 FFA_MEMORY_DEV_NGRE = 0x2,
62 FFA_MEMORY_DEV_GRE = 0x3,
63 };
64
65 enum ffa_memory_shareability {
66 FFA_MEMORY_SHARE_NON_SHAREABLE,
67 FFA_MEMORY_SHARE_RESERVED,
68 FFA_MEMORY_OUTER_SHAREABLE,
69 FFA_MEMORY_INNER_SHAREABLE,
70 };
71
72 typedef uint8_t ffa_memory_access_permissions_t;
73
74 /**
75 * This corresponds to table "Memory region attributes descriptor" of the FF-A
76 * 1.0 specification.
77 */
78 typedef uint8_t ffa_memory_attributes_t;
79
80 #define FFA_DATA_ACCESS_OFFSET (0x0U)
81 #define FFA_DATA_ACCESS_MASK ((0x3U) << FFA_DATA_ACCESS_OFFSET)
82
83 #define FFA_INSTRUCTION_ACCESS_OFFSET (0x2U)
84 #define FFA_INSTRUCTION_ACCESS_MASK ((0x3U) << FFA_INSTRUCTION_ACCESS_OFFSET)
85
86 #define FFA_MEMORY_TYPE_OFFSET (0x4U)
87 #define FFA_MEMORY_TYPE_MASK ((0x3U) << FFA_MEMORY_TYPE_OFFSET)
88
89 #define FFA_MEMORY_CACHEABILITY_OFFSET (0x2U)
90 #define FFA_MEMORY_CACHEABILITY_MASK ((0x3U) << FFA_MEMORY_CACHEABILITY_OFFSET)
91
92 #define FFA_MEMORY_SHAREABILITY_OFFSET (0x0U)
93 #define FFA_MEMORY_SHAREABILITY_MASK ((0x3U) << FFA_MEMORY_SHAREABILITY_OFFSET)
94
95 #define ATTR_FUNCTION_SET(name, container_type, offset, mask) \
96 static inline void ffa_set_##name##_attr(container_type *attr, \
97 const enum ffa_##name perm) \
98 { \
99 *attr = (*attr & ~(mask)) | ((perm << offset) & mask); \
100 }
101
102 #define ATTR_FUNCTION_GET(name, container_type, offset, mask) \
103 static inline enum ffa_##name ffa_get_##name##_attr( \
104 container_type attr) \
105 { \
106 return (enum ffa_##name)((attr & mask) >> offset); \
107 }
108
109 ATTR_FUNCTION_SET(data_access, ffa_memory_access_permissions_t,
110 FFA_DATA_ACCESS_OFFSET, FFA_DATA_ACCESS_MASK)
111 ATTR_FUNCTION_GET(data_access, ffa_memory_access_permissions_t,
112 FFA_DATA_ACCESS_OFFSET, FFA_DATA_ACCESS_MASK)
113
114 ATTR_FUNCTION_SET(instruction_access, ffa_memory_access_permissions_t,
115 FFA_INSTRUCTION_ACCESS_OFFSET, FFA_INSTRUCTION_ACCESS_MASK)
116 ATTR_FUNCTION_GET(instruction_access, ffa_memory_access_permissions_t,
117 FFA_INSTRUCTION_ACCESS_OFFSET, FFA_INSTRUCTION_ACCESS_MASK)
118
119 ATTR_FUNCTION_SET(memory_type, ffa_memory_attributes_t, FFA_MEMORY_TYPE_OFFSET,
120 FFA_MEMORY_TYPE_MASK)
121 ATTR_FUNCTION_GET(memory_type, ffa_memory_attributes_t, FFA_MEMORY_TYPE_OFFSET,
122 FFA_MEMORY_TYPE_MASK)
123
124 ATTR_FUNCTION_SET(memory_cacheability, ffa_memory_attributes_t,
125 FFA_MEMORY_CACHEABILITY_OFFSET, FFA_MEMORY_CACHEABILITY_MASK)
126 ATTR_FUNCTION_GET(memory_cacheability, ffa_memory_attributes_t,
127 FFA_MEMORY_CACHEABILITY_OFFSET, FFA_MEMORY_CACHEABILITY_MASK)
128
129 ATTR_FUNCTION_SET(memory_shareability, ffa_memory_attributes_t,
130 FFA_MEMORY_SHAREABILITY_OFFSET, FFA_MEMORY_SHAREABILITY_MASK)
131 ATTR_FUNCTION_GET(memory_shareability, ffa_memory_attributes_t,
132 FFA_MEMORY_SHAREABILITY_OFFSET, FFA_MEMORY_SHAREABILITY_MASK)
133
134 #define FFA_MEMORY_HANDLE_ALLOCATOR_MASK \
135 ((ffa_memory_handle_t)(UINT64_C(1) << 63))
136 #define FFA_MEMORY_HANDLE_ALLOCATOR_HYPERVISOR \
137 ((ffa_memory_handle_t)(UINT64_C(1) << 63))
138 #define FFA_MEMORY_HANDLE_INVALID (~UINT64_C(0))
139
140 /**
141 * A set of contiguous pages which is part of a memory region. This corresponds
142 * to table "Constituent memory region descriptor" of the FFA 1.0 specification.
143 */
144 struct ffa_memory_region_constituent {
145 /**
146 * The base IPA of the constituent memory region, aligned to 4 kiB page
147 * size granularity.
148 */
149 void *address;
150 /** The number of 4 kiB pages in the constituent memory region. */
151 uint32_t page_count;
152 /** Reserved field, must be 0. */
153 uint32_t reserved;
154 };
155
156 /**
157 * A set of pages comprising a memory region. This corresponds to table
158 * "Composite memory region descriptor" of the FFA 1.0 specification.
159 */
160 struct ffa_composite_memory_region {
161 /**
162 * The total number of 4 kiB pages included in this memory region. This
163 * must be equal to the sum of page counts specified in each
164 * `ffa_memory_region_constituent`.
165 */
166 uint32_t page_count;
167 /**
168 * The number of constituents (`ffa_memory_region_constituent`)
169 * included in this memory region range.
170 */
171 uint32_t constituent_count;
172 /** Reserved field, must be 0. */
173 uint64_t reserved_0;
174 /** An array of `constituent_count` memory region constituents. */
175 struct ffa_memory_region_constituent constituents[];
176 };
177
178 /**
179 * This corresponds to table "Memory access permissions descriptor" of the FFA
180 * 1.0 specification.
181 */
182 struct ffa_memory_region_attributes {
183 /** The ID of the VM to which the memory is being given or shared. */
184 ffa_id_t receiver;
185 /**
186 * The permissions with which the memory region should be mapped in the
187 * receiver's page table.
188 */
189 ffa_memory_access_permissions_t permissions;
190 /**
191 * Flags used during FFA_MEM_RETRIEVE_REQ and FFA_MEM_RETRIEVE_RESP
192 * for memory regions with multiple borrowers.
193 */
194 ffa_memory_receiver_flags_t flags;
195 };
196
197 /** Flags to control the behaviour of a memory sharing transaction. */
198 typedef uint32_t ffa_memory_region_flags_t;
199
200 /**
201 * Clear memory region contents after unmapping it from the sender and before
202 * mapping it for any receiver.
203 */
204 #define FFA_MEMORY_REGION_FLAG_CLEAR 0x1U
205
206 /**
207 * Whether the hypervisor may time slice the memory sharing or retrieval
208 * operation.
209 */
210 #define FFA_MEMORY_REGION_FLAG_TIME_SLICE 0x2U
211
212 /**
213 * Whether the hypervisor should clear the memory region after the receiver
214 * relinquishes it or is aborted.
215 */
216 #define FFA_MEMORY_REGION_FLAG_CLEAR_RELINQUISH 0x4U
217
218 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_MASK ((0x3U) << 3)
219 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_UNSPECIFIED ((0x0U) << 3)
220 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_SHARE ((0x1U) << 3)
221 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_LEND ((0x2U) << 3)
222 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_DONATE ((0x3U) << 3)
223
224 /** The maximum number of recipients a memory region may be sent to. */
225 #define MAX_MEM_SHARE_RECIPIENTS 1U
226
227
228 /* FFA Memory mapping modes. */
229 #define FFA_MEM_EXEC 0x8
230 #define FFA_MEM_NO_EXEC 0x4
231 #define FFA_MEM_RW 0x2
232 #define FFA_MEM_RO 0x1
233
234 /* FFA Memory Management mode flags. */
235 #define FFA_FLAG_SHARE_MEMORY (1U << 3)
236 #define FFA_FLAG_LEND_MEMORY (1U << 4)
237
238 #define FFA_FLAG_MEMORY_MASK (3U << 3)
239
240 #define FFA_MEM_HANDLE_LOW(x) (x & 0xFFFFFFFF)
241 #define FFA_MEM_HANDLE_HIGH(x) (x >> 32)
242
243 /* FF-A Run Macros. */
244 #define FFA_VCPU_ID_MASK 0xFFFF
245 #define FFA_RUN_VCPU(id) \
246 ((id >> 0) & FFA_VCPU_ID_MASK)
247 /**
248 * This corresponds to table "Endpoint memory access descriptor" of the FFA 1.0
249 * specification.
250 */
251 struct ffa_memory_access {
252 struct ffa_memory_region_attributes receiver_permissions;
253 /**
254 * Offset in bytes from the start of the outer `ffa_memory_region` to
255 * an `ffa_composite_memory_region` struct.
256 */
257 uint32_t composite_memory_region_offset;
258 uint64_t reserved_0;
259 };
260
261 /**
262 * Information about a set of pages which are being shared. This corresponds to
263 * table "Lend, donate or share memory transaction descriptor" of the FFA
264 * 1.0 specification. Note that it is also used for retrieve requests and
265 * responses.
266 */
267 struct ffa_memory_region {
268 /**
269 * The ID of the VM which originally sent the memory region, i.e. the
270 * owner.
271 */
272 ffa_id_t sender;
273 ffa_memory_attributes_t attributes;
274 /** Reserved field, must be 0. */
275 uint8_t reserved_0;
276 /** Flags to control behaviour of the transaction. */
277 ffa_memory_region_flags_t flags;
278 ffa_memory_handle_t handle;
279 /**
280 * An implementation defined value associated with the receiver and the
281 * memory region.
282 */
283 uint64_t tag;
284 /** Reserved field, must be 0. */
285 uint32_t reserved_1;
286 /**
287 * The number of `ffa_memory_access` entries included in this
288 * transaction.
289 */
290 uint32_t receiver_count;
291 /**
292 * An array of `attribute_count` endpoint memory access descriptors.
293 * Each one specifies a memory region offset, an endpoint and the
294 * attributes with which this memory region should be mapped in that
295 * endpoint's page table.
296 */
297 struct ffa_memory_access receivers[];
298 };
299
300 /**
301 * Descriptor used for FFA_MEM_RELINQUISH requests. This corresponds to table
302 * "Descriptor to relinquish a memory region" of the FFA 1.0 specification.
303 */
304 struct ffa_mem_relinquish {
305 ffa_memory_handle_t handle;
306 ffa_memory_region_flags_t flags;
307 uint32_t endpoint_count;
308 ffa_id_t endpoints[];
309 };
310
311
ffa_mem_relinquish_init(struct ffa_mem_relinquish * relinquish_request,ffa_memory_handle_t handle,ffa_memory_region_flags_t flags,ffa_id_t sender)312 static inline uint32_t ffa_mem_relinquish_init(
313 struct ffa_mem_relinquish *relinquish_request,
314 ffa_memory_handle_t handle, ffa_memory_region_flags_t flags,
315 ffa_id_t sender)
316 {
317 relinquish_request->handle = handle;
318 relinquish_request->flags = flags;
319 relinquish_request->endpoint_count = 1;
320 relinquish_request->endpoints[0] = sender;
321 return sizeof(struct ffa_mem_relinquish) + sizeof(ffa_id_t);
322 }
323
324 /**
325 * Gets the `ffa_composite_memory_region` for the given receiver from an
326 * `ffa_memory_region`, or NULL if it is not valid.
327 */
328 static inline struct ffa_composite_memory_region *
ffa_memory_region_get_composite(struct ffa_memory_region * memory_region,uint32_t receiver_index)329 ffa_memory_region_get_composite(struct ffa_memory_region *memory_region,
330 uint32_t receiver_index)
331 {
332 uint32_t offset = memory_region->receivers[receiver_index]
333 .composite_memory_region_offset;
334
335 if (offset == 0) {
336 return NULL;
337 }
338
339 return (struct ffa_composite_memory_region *)((uint8_t *)memory_region +
340 offset);
341 }
342
343
344 /**
345 * Initialises the given `ffa_memory_region` to be used for an
346 * `FFA_MEM_RETRIEVE_REQ` by the receiver of a memory transaction.
347 *
348 * Returns the size of the message written.
349 */
350 uint32_t ffa_memory_retrieve_request_init(
351 struct ffa_memory_region *memory_region, ffa_memory_handle_t handle,
352 ffa_id_t sender, ffa_id_t receiver, uint32_t tag,
353 ffa_memory_region_flags_t flags, enum ffa_data_access data_access,
354 enum ffa_instruction_access instruction_access,
355 enum ffa_memory_type type, enum ffa_memory_cacheability cacheability,
356 enum ffa_memory_shareability shareability);
357
358 tsp_args_t ffa_mem_frag_rx(uint64_t handle, uint32_t recv_length);
359 tsp_args_t ffa_mem_retrieve_req(uint32_t descriptor_length,
360 uint32_t fragment_length);
361 bool ffa_mem_relinquish(void);
362 bool ffa_rx_release(void);
363 bool memory_relinquish(struct ffa_mem_relinquish *m, uint64_t handle,
364 ffa_id_t id);
365 bool ffa_rxtx_map(uintptr_t send, uintptr_t recv, uint32_t pages);
366
367
368 #endif /* FFA_HELPERS_H */
369 #endif /* SPMC_AT_EL3 */
370