1 /*
2 * Copyright 2021 The Hafnium Authors.
3 *
4 * Use of this source code is governed by a BSD-style
5 * license that can be found in the LICENSE file or at
6 * https://opensource.org/licenses/BSD-3-Clause.
7 */
8
9 #pragma once
10
11 #include "hf/types.h"
12
13 #define FFA_VERSION_MAJOR 0x1
14 #define FFA_VERSION_MAJOR_OFFSET 16
15 #define FFA_VERSION_MAJOR_MASK 0x7FFF
16 #define FFA_VERSION_MINOR 0x1
17 #define FFA_VERSION_MINOR_OFFSET 0
18 #define FFA_VERSION_MINOR_MASK 0xFFFF
19
20 #define MAKE_FFA_VERSION(major, minor) \
21 ((((major)&FFA_VERSION_MAJOR_MASK) << FFA_VERSION_MAJOR_OFFSET) | \
22 (((minor)&FFA_VERSION_MINOR_MASK) << FFA_VERSION_MINOR_OFFSET))
23 #define FFA_VERSION_COMPILED \
24 MAKE_FFA_VERSION(FFA_VERSION_MAJOR, FFA_VERSION_MINOR)
25
26 /* clang-format off */
27
28 #define FFA_LOW_32_ID 0x84000060
29 #define FFA_HIGH_32_ID 0x8400007F
30 #define FFA_LOW_64_ID 0xC4000060
31 #define FFA_HIGH_64_ID 0xC400007F
32
33 /* FF-A function identifiers. */
34 #define FFA_ERROR_32 0x84000060
35 #define FFA_SUCCESS_32 0x84000061
36 #define FFA_SUCCESS_64 0xC4000061
37 #define FFA_INTERRUPT_32 0x84000062
38 #define FFA_VERSION_32 0x84000063
39 #define FFA_FEATURES_32 0x84000064
40 #define FFA_RX_RELEASE_32 0x84000065
41 #define FFA_RXTX_MAP_32 0x84000066
42 #define FFA_RXTX_MAP_64 0xC4000066
43 #define FFA_RXTX_UNMAP_32 0x84000067
44 #define FFA_PARTITION_INFO_GET_32 0x84000068
45 #define FFA_ID_GET_32 0x84000069
46 #define FFA_MSG_POLL_32 0x8400006A /* Legacy FF-A v1.0 */
47 #define FFA_MSG_WAIT_32 0x8400006B
48 #define FFA_YIELD_32 0x8400006C
49 #define FFA_RUN_32 0x8400006D
50 #define FFA_MSG_SEND_32 0x8400006E /* Legacy FF-A v1.0 */
51 #define FFA_MSG_SEND_DIRECT_REQ_32 0x8400006F
52 #define FFA_MSG_SEND_DIRECT_REQ_64 0xC400006F
53 #define FFA_MSG_SEND_DIRECT_RESP_32 0x84000070
54 #define FFA_MSG_SEND_DIRECT_RESP_64 0xC4000070
55 #define FFA_MEM_DONATE_32 0x84000071
56 #define FFA_MEM_LEND_32 0x84000072
57 #define FFA_MEM_SHARE_32 0x84000073
58 #define FFA_MEM_RETRIEVE_REQ_32 0x84000074
59 #define FFA_MEM_RETRIEVE_RESP_32 0x84000075
60 #define FFA_MEM_RELINQUISH_32 0x84000076
61 #define FFA_MEM_RECLAIM_32 0x84000077
62 #define FFA_MEM_FRAG_RX_32 0x8400007A
63 #define FFA_MEM_FRAG_TX_32 0x8400007B
64 #define FFA_NORMAL_WORLD_RESUME 0x8400007C
65
66 /* FF-A v1.1 */
67 #define FFA_NOTIFICATION_BITMAP_CREATE_32 0x8400007D
68 #define FFA_NOTIFICATION_BITMAP_DESTROY_32 0x8400007E
69 #define FFA_NOTIFICATION_BIND_32 0x8400007F
70 #define FFA_NOTIFICATION_UNBIND_32 0x84000080
71 #define FFA_NOTIFICATION_SET_32 0x84000081
72 #define FFA_NOTIFICATION_GET_32 0x84000082
73 #define FFA_NOTIFICATION_INFO_GET_64 0xC4000083
74 #define FFA_RX_ACQUIRE_32 0x84000084
75 #define FFA_SPM_ID_GET_32 0x84000085
76 #define FFA_MSG_SEND2_32 0x84000086
77 #define FFA_SECONDARY_EP_REGISTER_64 0xC4000087
78 #define FFA_MEM_PERM_GET_32 0x84000088
79 #define FFA_MEM_PERM_SET_32 0x84000089
80 #define FFA_MEM_PERM_GET_64 0xC4000088
81 #define FFA_MEM_PERM_SET_64 0xC4000089
82
83 /* Implementation-defined ABIs. */
84 #define FFA_CONSOLE_LOG_32 0x8400008A
85 #define FFA_CONSOLE_LOG_64 0xC400008A
86
87 /* FF-A error codes. */
88 #define FFA_NOT_SUPPORTED INT32_C(-1)
89 #define FFA_INVALID_PARAMETERS INT32_C(-2)
90 #define FFA_NO_MEMORY INT32_C(-3)
91 #define FFA_BUSY INT32_C(-4)
92 #define FFA_INTERRUPTED INT32_C(-5)
93 #define FFA_DENIED INT32_C(-6)
94 #define FFA_RETRY INT32_C(-7)
95 #define FFA_ABORTED INT32_C(-8)
96 #define FFA_NO_DATA INT32_C(-9)
97
98 /* clang-format on */
99
100 /**
101 * FF-A Feature ID, to be used with interface FFA_FEATURES.
102 * As defined in the FF-A v1.1 Beta specification, table 13.10, in section
103 * 13.2.
104 */
105
106 #define FFA_FEATURES_FUNC_ID_MASK (UINT32_C(1) << 31)
107 #define FFA_FEATURES_FEATURE_ID_MASK UINT32_C(0x7F)
108
109 /* Query interrupt ID of Notification Pending Interrupt. */
110 #define FFA_FEATURE_NPI 0x1U
111
112 /* Query interrupt ID of Schedule Receiver Interrupt. */
113 #define FFA_FEATURE_SRI 0x2U
114
115 /* Query interrupt ID of the Managed Exit Interrupt. */
116 #define FFA_FEATURE_MEI 0x3U
117
118 /* FF-A function specific constants. */
119 #define FFA_MSG_RECV_BLOCK 0x1
120 #define FFA_MSG_RECV_BLOCK_MASK 0x1
121
122 #define FFA_MSG_SEND_NOTIFY 0x1
123 #define FFA_MSG_SEND_NOTIFY_MASK 0x1
124
125 #define FFA_MEM_RECLAIM_CLEAR 0x1
126
127 #define FFA_SLEEP_INDEFINITE 0
128
129 #define FFA_MEM_PERM_RO UINT32_C(0x7)
130 #define FFA_MEM_PERM_RW UINT32_C(0x5)
131 #define FFA_MEM_PERM_RX UINT32_C(0x3)
132
133 /*
134 * Defined in Table 13.31 in the FF-A v1.1 BETA0 specification.
135 * The Partition count flag is used by FFA_PARTITION_INFO_GET to specify
136 * if partition info descriptors should be returned or just the count.
137 */
138 #define FFA_PARTITION_COUNT_FLAG 0x1
139 #define FFA_PARTITION_COUNT_FLAG_MASK 0x1
140
141 /**
142 * For use where the FF-A specification refers explicitly to '4K pages'. Not to
143 * be confused with PAGE_SIZE, which is the translation granule Hafnium is
144 * configured to use.
145 */
146 #define FFA_PAGE_SIZE 4096
147
148 /** The ID of a VM. These are assigned sequentially starting with an offset. */
149 typedef uint16_t ffa_vm_id_t;
150
151 /**
152 * Partition message header as specified by table 6.2 from FF-A v1.1 EAC0
153 * specification.
154 */
155 struct ffa_partition_rxtx_header {
156 uint32_t flags; /* MBZ */
157 uint32_t reserved;
158 /* Offset from the beginning of the buffer to the message payload. */
159 uint32_t offset;
160 /* Sender(Bits[31:16]) and Receiver(Bits[15:0]) endpoint IDs. */
161 uint32_t sender_receiver;
162 /* Size of message in buffer. */
163 uint32_t size;
164 };
165
166 #define FFA_RXTX_HEADER_SIZE sizeof(struct ffa_partition_rxtx_header)
167 #define FFA_RXTX_SENDER_SHIFT (0x10U)
168
ffa_rxtx_header_init(ffa_vm_id_t sender,ffa_vm_id_t receiver,uint32_t size,struct ffa_partition_rxtx_header * header)169 static inline void ffa_rxtx_header_init(
170 ffa_vm_id_t sender, ffa_vm_id_t receiver, uint32_t size,
171 struct ffa_partition_rxtx_header *header)
172 {
173 header->flags = 0;
174 header->reserved = 0;
175 header->offset = FFA_RXTX_HEADER_SIZE;
176 header->sender_receiver =
177 (uint32_t)(receiver | (sender << FFA_RXTX_SENDER_SHIFT));
178 header->size = size;
179 }
180
ffa_rxtx_header_sender(const struct ffa_partition_rxtx_header * h)181 static inline ffa_vm_id_t ffa_rxtx_header_sender(
182 const struct ffa_partition_rxtx_header *h)
183 {
184 return (ffa_vm_id_t)(h->sender_receiver >> FFA_RXTX_SENDER_SHIFT);
185 }
186
ffa_rxtx_header_receiver(const struct ffa_partition_rxtx_header * h)187 static inline ffa_vm_id_t ffa_rxtx_header_receiver(
188 const struct ffa_partition_rxtx_header *h)
189 {
190 return (ffa_vm_id_t)(h->sender_receiver);
191 }
192
193 /* The maximum length possible for a single message. */
194 #define FFA_PARTITION_MSG_PAYLOAD_MAX (HF_MAILBOX_SIZE - FFA_RXTX_HEADER_SIZE)
195
196 struct ffa_partition_msg {
197 struct ffa_partition_rxtx_header header;
198 char payload[FFA_PARTITION_MSG_PAYLOAD_MAX];
199 };
200
201 /* The maximum length possible for a single message. */
202 #define FFA_MSG_PAYLOAD_MAX HF_MAILBOX_SIZE
203
204 enum ffa_data_access {
205 FFA_DATA_ACCESS_NOT_SPECIFIED,
206 FFA_DATA_ACCESS_RO,
207 FFA_DATA_ACCESS_RW,
208 FFA_DATA_ACCESS_RESERVED,
209 };
210
211 enum ffa_instruction_access {
212 FFA_INSTRUCTION_ACCESS_NOT_SPECIFIED,
213 FFA_INSTRUCTION_ACCESS_NX,
214 FFA_INSTRUCTION_ACCESS_X,
215 FFA_INSTRUCTION_ACCESS_RESERVED,
216 };
217
218 enum ffa_memory_type {
219 FFA_MEMORY_NOT_SPECIFIED_MEM,
220 FFA_MEMORY_DEVICE_MEM,
221 FFA_MEMORY_NORMAL_MEM,
222 };
223
224 enum ffa_memory_cacheability {
225 FFA_MEMORY_CACHE_RESERVED = 0x0,
226 FFA_MEMORY_CACHE_NON_CACHEABLE = 0x1,
227 FFA_MEMORY_CACHE_RESERVED_1 = 0x2,
228 FFA_MEMORY_CACHE_WRITE_BACK = 0x3,
229 FFA_MEMORY_DEV_NGNRNE = 0x0,
230 FFA_MEMORY_DEV_NGNRE = 0x1,
231 FFA_MEMORY_DEV_NGRE = 0x2,
232 FFA_MEMORY_DEV_GRE = 0x3,
233 };
234
235 enum ffa_memory_shareability {
236 FFA_MEMORY_SHARE_NON_SHAREABLE,
237 FFA_MEMORY_SHARE_RESERVED,
238 FFA_MEMORY_OUTER_SHAREABLE,
239 FFA_MEMORY_INNER_SHAREABLE,
240 };
241
242 typedef uint8_t ffa_memory_access_permissions_t;
243
244 /**
245 * This corresponds to table 44 of the FF-A 1.0 EAC specification, "Memory
246 * region attributes descriptor".
247 */
248 typedef uint8_t ffa_memory_attributes_t;
249
250 #define FFA_DATA_ACCESS_OFFSET (0x0U)
251 #define FFA_DATA_ACCESS_MASK ((0x3U) << FFA_DATA_ACCESS_OFFSET)
252
253 #define FFA_INSTRUCTION_ACCESS_OFFSET (0x2U)
254 #define FFA_INSTRUCTION_ACCESS_MASK ((0x3U) << FFA_INSTRUCTION_ACCESS_OFFSET)
255
256 #define FFA_MEMORY_TYPE_OFFSET (0x4U)
257 #define FFA_MEMORY_TYPE_MASK ((0x3U) << FFA_MEMORY_TYPE_OFFSET)
258
259 #define FFA_MEMORY_CACHEABILITY_OFFSET (0x2U)
260 #define FFA_MEMORY_CACHEABILITY_MASK ((0x3U) << FFA_MEMORY_CACHEABILITY_OFFSET)
261
262 #define FFA_MEMORY_SHAREABILITY_OFFSET (0x0U)
263 #define FFA_MEMORY_SHAREABILITY_MASK ((0x3U) << FFA_MEMORY_SHAREABILITY_OFFSET)
264
265 #define ATTR_FUNCTION_SET(name, container_type, offset, mask) \
266 static inline void ffa_set_##name##_attr(container_type *attr, \
267 const enum ffa_##name perm) \
268 { \
269 *attr = (*attr & ~(mask)) | ((perm << offset) & mask); \
270 }
271
272 #define ATTR_FUNCTION_GET(name, container_type, offset, mask) \
273 static inline enum ffa_##name ffa_get_##name##_attr( \
274 container_type attr) \
275 { \
276 return (enum ffa_##name)((attr & mask) >> offset); \
277 }
278
279 ATTR_FUNCTION_SET(data_access, ffa_memory_access_permissions_t,
280 FFA_DATA_ACCESS_OFFSET, FFA_DATA_ACCESS_MASK)
281 ATTR_FUNCTION_GET(data_access, ffa_memory_access_permissions_t,
282 FFA_DATA_ACCESS_OFFSET, FFA_DATA_ACCESS_MASK)
283
284 ATTR_FUNCTION_SET(instruction_access, ffa_memory_access_permissions_t,
285 FFA_INSTRUCTION_ACCESS_OFFSET, FFA_INSTRUCTION_ACCESS_MASK)
286 ATTR_FUNCTION_GET(instruction_access, ffa_memory_access_permissions_t,
287 FFA_INSTRUCTION_ACCESS_OFFSET, FFA_INSTRUCTION_ACCESS_MASK)
288
289 ATTR_FUNCTION_SET(memory_type, ffa_memory_attributes_t, FFA_MEMORY_TYPE_OFFSET,
290 FFA_MEMORY_TYPE_MASK)
291 ATTR_FUNCTION_GET(memory_type, ffa_memory_attributes_t, FFA_MEMORY_TYPE_OFFSET,
292 FFA_MEMORY_TYPE_MASK)
293
294 ATTR_FUNCTION_SET(memory_cacheability, ffa_memory_attributes_t,
295 FFA_MEMORY_CACHEABILITY_OFFSET, FFA_MEMORY_CACHEABILITY_MASK)
296 ATTR_FUNCTION_GET(memory_cacheability, ffa_memory_attributes_t,
297 FFA_MEMORY_CACHEABILITY_OFFSET, FFA_MEMORY_CACHEABILITY_MASK)
298
299 ATTR_FUNCTION_SET(memory_shareability, ffa_memory_attributes_t,
300 FFA_MEMORY_SHAREABILITY_OFFSET, FFA_MEMORY_SHAREABILITY_MASK)
301 ATTR_FUNCTION_GET(memory_shareability, ffa_memory_attributes_t,
302 FFA_MEMORY_SHAREABILITY_OFFSET, FFA_MEMORY_SHAREABILITY_MASK)
303
304 /**
305 * A globally-unique ID assigned by the hypervisor for a region of memory being
306 * sent between VMs.
307 */
308 typedef uint64_t ffa_memory_handle_t;
309
310 #define FFA_MEMORY_HANDLE_ALLOCATOR_MASK \
311 ((ffa_memory_handle_t)(UINT64_C(1) << 63))
312 #define FFA_MEMORY_HANDLE_ALLOCATOR_HYPERVISOR \
313 ((ffa_memory_handle_t)(UINT64_C(1) << 63))
314
315 #define FFA_MEMORY_HANDLE_ALLOCATOR_SPMC (UINT64_C(0) << 63)
316 #define FFA_MEMORY_HANDLE_INVALID (~UINT64_C(0))
317
318 /**
319 * A count of VMs. This has the same range as the VM IDs but we give it a
320 * different name to make the different semantics clear.
321 */
322 typedef ffa_vm_id_t ffa_vm_count_t;
323
324 /** The index of a vCPU within a particular VM. */
325 typedef uint16_t ffa_vcpu_index_t;
326
327 /**
328 * A count of vCPUs. This has the same range as the vCPU indices but we give it
329 * a different name to make the different semantics clear.
330 */
331 typedef ffa_vcpu_index_t ffa_vcpu_count_t;
332
333 /** Parameter and return type of FF-A functions. */
334 struct ffa_value {
335 uint64_t func;
336 uint64_t arg1;
337 uint64_t arg2;
338 uint64_t arg3;
339 uint64_t arg4;
340 uint64_t arg5;
341 uint64_t arg6;
342 uint64_t arg7;
343 };
344
ffa_func_id(struct ffa_value args)345 static inline uint32_t ffa_func_id(struct ffa_value args)
346 {
347 return args.func;
348 }
349
ffa_error_code(struct ffa_value val)350 static inline int32_t ffa_error_code(struct ffa_value val)
351 {
352 return (int32_t)val.arg2;
353 }
354
ffa_sender(struct ffa_value args)355 static inline ffa_vm_id_t ffa_sender(struct ffa_value args)
356 {
357 return (args.arg1 >> 16) & 0xffff;
358 }
359
ffa_receiver(struct ffa_value args)360 static inline ffa_vm_id_t ffa_receiver(struct ffa_value args)
361 {
362 return args.arg1 & 0xffff;
363 }
364
ffa_msg_send_size(struct ffa_value args)365 static inline uint32_t ffa_msg_send_size(struct ffa_value args)
366 {
367 return args.arg3;
368 }
369
ffa_msg_send2_flags(struct ffa_value args)370 static inline uint32_t ffa_msg_send2_flags(struct ffa_value args)
371 {
372 return args.arg2;
373 }
374
ffa_partition_info_get_count(struct ffa_value args)375 static inline uint32_t ffa_partition_info_get_count(struct ffa_value args)
376 {
377 return args.arg2;
378 }
379
ffa_assemble_handle(uint32_t a1,uint32_t a2)380 static inline ffa_memory_handle_t ffa_assemble_handle(uint32_t a1, uint32_t a2)
381 {
382 return (uint64_t)a1 | (uint64_t)a2 << 32;
383 }
384
ffa_mem_success_handle(struct ffa_value args)385 static inline ffa_memory_handle_t ffa_mem_success_handle(struct ffa_value args)
386 {
387 return ffa_assemble_handle(args.arg2, args.arg3);
388 }
389
ffa_frag_handle(struct ffa_value args)390 static inline ffa_memory_handle_t ffa_frag_handle(struct ffa_value args)
391 {
392 return ffa_assemble_handle(args.arg1, args.arg2);
393 }
394
ffa_mem_success(ffa_memory_handle_t handle)395 static inline struct ffa_value ffa_mem_success(ffa_memory_handle_t handle)
396 {
397 return (struct ffa_value){.func = FFA_SUCCESS_32,
398 .arg2 = (uint32_t)handle,
399 .arg3 = (uint32_t)(handle >> 32)};
400 }
401
ffa_vm_id(struct ffa_value args)402 static inline ffa_vm_id_t ffa_vm_id(struct ffa_value args)
403 {
404 return (args.arg1 >> 16) & 0xffff;
405 }
406
ffa_vcpu_index(struct ffa_value args)407 static inline ffa_vcpu_index_t ffa_vcpu_index(struct ffa_value args)
408 {
409 return args.arg1 & 0xffff;
410 }
411
ffa_vm_vcpu(ffa_vm_id_t vm_id,ffa_vcpu_index_t vcpu_index)412 static inline uint64_t ffa_vm_vcpu(ffa_vm_id_t vm_id,
413 ffa_vcpu_index_t vcpu_index)
414 {
415 return ((uint32_t)vm_id << 16) | vcpu_index;
416 }
417
ffa_frag_sender(struct ffa_value args)418 static inline ffa_vm_id_t ffa_frag_sender(struct ffa_value args)
419 {
420 return (args.arg4 >> 16) & 0xffff;
421 }
422
ffa_feature_intid(struct ffa_value args)423 static inline uint32_t ffa_feature_intid(struct ffa_value args)
424 {
425 return (uint32_t)args.arg2;
426 }
427
ffa_fwk_msg(struct ffa_value args)428 static inline uint32_t ffa_fwk_msg(struct ffa_value args)
429 {
430 return (uint32_t)args.arg2;
431 }
432
433 /**
434 * Holds the UUID in a struct that is mappable directly to the SMCC calling
435 * convention, which is used for FF-A calls.
436 *
437 * Refer to table 84 of the FF-A 1.0 EAC specification as well as section 5.3
438 * of the SMCC Spec 1.2.
439 */
440 struct ffa_uuid {
441 uint32_t uuid[4];
442 };
443
ffa_uuid_init(uint32_t w0,uint32_t w1,uint32_t w2,uint32_t w3,struct ffa_uuid * uuid)444 static inline void ffa_uuid_init(uint32_t w0, uint32_t w1, uint32_t w2,
445 uint32_t w3, struct ffa_uuid *uuid)
446 {
447 uuid->uuid[0] = w0;
448 uuid->uuid[1] = w1;
449 uuid->uuid[2] = w2;
450 uuid->uuid[3] = w3;
451 }
452
ffa_uuid_equal(const struct ffa_uuid * uuid1,const struct ffa_uuid * uuid2)453 static inline bool ffa_uuid_equal(const struct ffa_uuid *uuid1,
454 const struct ffa_uuid *uuid2)
455 {
456 return (uuid1->uuid[0] == uuid2->uuid[0]) &&
457 (uuid1->uuid[1] == uuid2->uuid[1]) &&
458 (uuid1->uuid[2] == uuid2->uuid[2]) &&
459 (uuid1->uuid[3] == uuid2->uuid[3]);
460 }
461
ffa_uuid_is_null(const struct ffa_uuid * uuid)462 static inline bool ffa_uuid_is_null(const struct ffa_uuid *uuid)
463 {
464 return (uuid->uuid[0] == 0) && (uuid->uuid[1] == 0) &&
465 (uuid->uuid[2] == 0) && (uuid->uuid[3] == 0);
466 }
467
468 /**
469 * Flags to determine the partition properties, as required by
470 * FFA_PARTITION_INFO_GET.
471 *
472 * The values of the flags are specified in table 82 of the FF-A 1.0 EAC
473 * specification, "Partition information descriptor, partition properties".
474 */
475 typedef uint32_t ffa_partition_properties_t;
476
477 /** Partition property: partition supports receipt of direct requests. */
478 #define FFA_PARTITION_DIRECT_REQ_RECV 0x1
479
480 /** Partition property: partition can send direct requests. */
481 #define FFA_PARTITION_DIRECT_REQ_SEND 0x2
482
483 /** Partition property: partition can send and receive indirect messages. */
484 #define FFA_PARTITION_INDIRECT_MSG 0x4
485
486 /** Partition property: partition can receive notifications. */
487 #define FFA_PARTITION_NOTIFICATION 0x8
488
489 /**
490 * Holds information returned for each partition by the FFA_PARTITION_INFO_GET
491 * interface.
492 * This corresponds to table 13.34 of the FF-A 1.1 BETA0 EAC specification,
493 * "Partition information descriptor".
494 */
495 struct ffa_partition_info {
496 ffa_vm_id_t vm_id;
497 ffa_vcpu_count_t vcpu_count;
498 ffa_partition_properties_t properties;
499 struct ffa_uuid uuid;
500 };
501
502 /**
503 * Create a struct for the "Partition information descriptor" defined for v1.0
504 * which can be returned to v1.0 endpoints.
505 * This corresponds to table 82 of the FF-A 1.0 EAC specification, "Partition
506 * information descriptor".
507 */
508
509 struct ffa_partition_info_v1_0 {
510 ffa_vm_id_t vm_id;
511 ffa_vcpu_count_t vcpu_count;
512 ffa_partition_properties_t properties;
513 };
514
515 /** Length in bytes of the name in boot information descriptor. */
516 #define FFA_BOOT_INFO_NAME_LEN 16
517
518 /**
519 * The FF-A boot info descriptor, as defined in table 5.8 of section 5.4.1, of
520 * the FF-A v1.1 EAC0 specification.
521 */
522 struct ffa_boot_info_desc {
523 char name[FFA_BOOT_INFO_NAME_LEN];
524 uint8_t type;
525 uint8_t reserved;
526 uint16_t flags;
527 uint32_t size;
528 uint64_t content;
529 };
530
531 /** FF-A boot information type mask. */
532 #define FFA_BOOT_INFO_TYPE_SHIFT 7
533 #define FFA_BOOT_INFO_TYPE_MASK (0x1U << FFA_BOOT_INFO_TYPE_SHIFT)
534 #define FFA_BOOT_INFO_TYPE_STD 0U
535 #define FFA_BOOT_INFO_TYPE_IMPDEF 1U
536
537 /** Standard boot info type IDs. */
538 #define FFA_BOOT_INFO_TYPE_ID_MASK 0x7FU
539 #define FFA_BOOT_INFO_TYPE_ID_FDT 0U
540 #define FFA_BOOT_INFO_TYPE_ID_HOB 1U
541
542 /** FF-A Boot Info descriptors flags. */
543 #define FFA_BOOT_INFO_FLAG_MBZ_MASK 0xFFF0U
544
545 /** Bits [1:0] encode the format of the name field in ffa_boot_info_desc. */
546 #define FFA_BOOT_INFO_FLAG_NAME_FORMAT_SHIFT 0U
547 #define FFA_BOOT_INFO_FLAG_NAME_FORMAT_MASK \
548 (0x3U << FFA_BOOT_INFO_FLAG_NAME_FORMAT_SHIFT)
549 #define FFA_BOOT_INFO_FLAG_NAME_FORMAT_STRING 0x0U
550 #define FFA_BOOT_INFO_FLAG_NAME_FORMAT_UUID 0x1U
551
552 /** Bits [3:2] encode the format of the content field in ffa_boot_info_desc. */
553 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_SHIFT 2
554 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_MASK \
555 (0x3U << FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_SHIFT)
556 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_VALUE 0x1U
557 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_ADDR 0x0U
558
ffa_boot_info_content_format(struct ffa_boot_info_desc * desc)559 static inline uint16_t ffa_boot_info_content_format(
560 struct ffa_boot_info_desc *desc)
561 {
562 return (desc->flags & FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_MASK) >>
563 FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_SHIFT;
564 }
565
ffa_boot_info_name_format(struct ffa_boot_info_desc * desc)566 static inline uint16_t ffa_boot_info_name_format(
567 struct ffa_boot_info_desc *desc)
568 {
569 return (desc->flags & FFA_BOOT_INFO_FLAG_NAME_FORMAT_MASK) >>
570 FFA_BOOT_INFO_FLAG_NAME_FORMAT_SHIFT;
571 }
572
ffa_boot_info_type_id(struct ffa_boot_info_desc * desc)573 static inline uint8_t ffa_boot_info_type_id(struct ffa_boot_info_desc *desc)
574 {
575 return desc->type & FFA_BOOT_INFO_TYPE_ID_MASK;
576 }
577
ffa_boot_info_type(struct ffa_boot_info_desc * desc)578 static inline uint8_t ffa_boot_info_type(struct ffa_boot_info_desc *desc)
579 {
580 return (desc->type & FFA_BOOT_INFO_TYPE_MASK) >>
581 FFA_BOOT_INFO_TYPE_SHIFT;
582 }
583
584 /** Length in bytes of the signature in the boot descriptor. */
585 #define FFA_BOOT_INFO_HEADER_SIGNATURE_LEN 4
586
587 /**
588 * The FF-A boot information header, as defined in table 5.9 of section 5.4.2,
589 * of the FF-A v1.1 EAC0 specification.
590 */
591 struct ffa_boot_info_header {
592 uint32_t signature;
593 uint32_t version;
594 uint32_t info_blob_size;
595 uint32_t desc_size;
596 uint32_t desc_count;
597 uint32_t desc_offset;
598 uint64_t reserved;
599 struct ffa_boot_info_desc boot_info[];
600 };
601
602 /**
603 * FF-A v1.1 specification restricts the number of notifications to a maximum
604 * of 64. Following all possible bitmaps.
605 */
606 #define FFA_NOTIFICATION_MASK(ID) (UINT64_C(1) << ID)
607
608 typedef uint64_t ffa_notifications_bitmap_t;
609
610 #define MAX_FFA_NOTIFICATIONS 64U
611
612 /**
613 * Flag for notification bind and set, to specify call is about per-vCPU
614 * notifications.
615 */
616 #define FFA_NOTIFICATION_FLAG_PER_VCPU (UINT32_C(1) << 0)
617
618 #define FFA_NOTIFICATION_SPM_BUFFER_FULL_MASK FFA_NOTIFICATION_MASK(0)
619 #define FFA_NOTIFICATION_HYP_BUFFER_FULL_MASK FFA_NOTIFICATION_MASK(32)
620
621 /**
622 * Helper functions to check for buffer full notification.
623 */
is_ffa_hyp_buffer_full_notification(ffa_notifications_bitmap_t framework)624 static inline bool is_ffa_hyp_buffer_full_notification(
625 ffa_notifications_bitmap_t framework)
626 {
627 return (framework & FFA_NOTIFICATION_HYP_BUFFER_FULL_MASK) != 0;
628 }
629
is_ffa_spm_buffer_full_notification(ffa_notifications_bitmap_t framework)630 static inline bool is_ffa_spm_buffer_full_notification(
631 ffa_notifications_bitmap_t framework)
632 {
633 return (framework & FFA_NOTIFICATION_SPM_BUFFER_FULL_MASK) != 0;
634 }
635
636 /**
637 * Helper function to assemble a 64-bit sized bitmap, from the 32-bit sized lo
638 * and hi.
639 * Helpful as FF-A specification defines that the notifications interfaces
640 * arguments are 32-bit registers.
641 */
ffa_notifications_bitmap(uint32_t lo,uint32_t hi)642 static inline ffa_notifications_bitmap_t ffa_notifications_bitmap(uint32_t lo,
643 uint32_t hi)
644 {
645 return (ffa_notifications_bitmap_t)hi << 32U | lo;
646 }
647
ffa_notification_get_from_sp(struct ffa_value val)648 static inline ffa_notifications_bitmap_t ffa_notification_get_from_sp(
649 struct ffa_value val)
650 {
651 return ffa_notifications_bitmap((uint32_t)val.arg2, (uint32_t)val.arg3);
652 }
653
ffa_notification_get_from_vm(struct ffa_value val)654 static inline ffa_notifications_bitmap_t ffa_notification_get_from_vm(
655 struct ffa_value val)
656 {
657 return ffa_notifications_bitmap((uint32_t)val.arg4, (uint32_t)val.arg5);
658 }
659
ffa_notification_get_from_framework(struct ffa_value val)660 static inline ffa_notifications_bitmap_t ffa_notification_get_from_framework(
661 struct ffa_value val)
662 {
663 return ffa_notifications_bitmap((uint32_t)val.arg6, (uint32_t)val.arg7);
664 }
665
666 /**
667 * Flags used in calls to FFA_NOTIFICATION_GET interface.
668 */
669 #define FFA_NOTIFICATION_FLAG_BITMAP_SP (UINT32_C(1) << 0)
670 #define FFA_NOTIFICATION_FLAG_BITMAP_VM (UINT32_C(1) << 1)
671 #define FFA_NOTIFICATION_FLAG_BITMAP_SPM (UINT32_C(1) << 2)
672 #define FFA_NOTIFICATION_FLAG_BITMAP_HYP (UINT32_C(1) << 3)
673
674 /* Flag to configure notification as being per vCPU. */
675 #define FFA_NOTIFICATIONS_FLAG_PER_VCPU (UINT32_C(1) << 0)
676
677 /** Flag for FFA_NOTIFICATION_SET to delay Schedule Receiver Interrupt */
678 #define FFA_NOTIFICATIONS_FLAG_DELAY_SRI (UINT32_C(1) << 1)
679
680 #define FFA_NOTIFICATIONS_FLAGS_VCPU_ID(id) \
681 ((((uint32_t)(id)) & UINT32_C(0xffff)) << 16)
682
ffa_notifications_get_vcpu(struct ffa_value args)683 static inline ffa_vcpu_index_t ffa_notifications_get_vcpu(struct ffa_value args)
684 {
685 return (ffa_vcpu_index_t)(args.arg1 >> 16 & 0xffffU);
686 }
687
688 /**
689 * The max number of IDs for return of FFA_NOTIFICATION_INFO_GET.
690 */
691 #define FFA_NOTIFICATIONS_INFO_GET_MAX_IDS 20U
692
693 /**
694 * Number of registers to use in successfull return of interface
695 * FFA_NOTIFICATION_INFO_GET.
696 */
697 #define FFA_NOTIFICATIONS_INFO_GET_REGS_RET 5U
698
699 #define FFA_NOTIFICATIONS_INFO_GET_FLAG_MORE_PENDING 0x1U
700
701 /**
702 * Helper macros for return parameter encoding as described in section 17.7.1
703 * of the FF-A v1.1 Beta0 specification.
704 */
705 #define FFA_NOTIFICATIONS_LISTS_COUNT_SHIFT 0x7U
706 #define FFA_NOTIFICATIONS_LISTS_COUNT_MASK 0x1fU
707 #define FFA_NOTIFICATIONS_LIST_SHIFT(l) (2 * (l - 1) + 12)
708 #define FFA_NOTIFICATIONS_LIST_SIZE_MASK 0x3U
709
ffa_notification_info_get_lists_count(struct ffa_value args)710 static inline uint32_t ffa_notification_info_get_lists_count(
711 struct ffa_value args)
712 {
713 return (uint32_t)(args.arg2 >> FFA_NOTIFICATIONS_LISTS_COUNT_SHIFT) &
714 FFA_NOTIFICATIONS_LISTS_COUNT_MASK;
715 }
716
ffa_notification_info_get_list_size(struct ffa_value args,unsigned int list_idx)717 static inline uint32_t ffa_notification_info_get_list_size(
718 struct ffa_value args, unsigned int list_idx)
719 {
720 return ((uint32_t)args.arg2 >> FFA_NOTIFICATIONS_LIST_SHIFT(list_idx)) &
721 FFA_NOTIFICATIONS_LIST_SIZE_MASK;
722 }
723
ffa_notification_info_get_more_pending(struct ffa_value args)724 static inline bool ffa_notification_info_get_more_pending(struct ffa_value args)
725 {
726 return (args.arg2 & FFA_NOTIFICATIONS_INFO_GET_FLAG_MORE_PENDING) != 0U;
727 }
728
729 /**
730 * A set of contiguous pages which is part of a memory region. This corresponds
731 * to table 40 of the FF-A 1.0 EAC specification, "Constituent memory region
732 * descriptor".
733 */
734 struct ffa_memory_region_constituent {
735 /**
736 * The base IPA of the constituent memory region, aligned to 4 kiB page
737 * size granularity.
738 */
739 uint64_t address;
740 /** The number of 4 kiB pages in the constituent memory region. */
741 uint32_t page_count;
742 /** Reserved field, must be 0. */
743 uint32_t reserved;
744 };
745
746 /**
747 * A set of pages comprising a memory region. This corresponds to table 39 of
748 * the FF-A 1.0 EAC specification, "Composite memory region descriptor".
749 */
750 struct ffa_composite_memory_region {
751 /**
752 * The total number of 4 kiB pages included in this memory region. This
753 * must be equal to the sum of page counts specified in each
754 * `ffa_memory_region_constituent`.
755 */
756 uint32_t page_count;
757 /**
758 * The number of constituents (`ffa_memory_region_constituent`)
759 * included in this memory region range.
760 */
761 uint32_t constituent_count;
762 /** Reserved field, must be 0. */
763 uint64_t reserved_0;
764 /** An array of `constituent_count` memory region constituents. */
765 struct ffa_memory_region_constituent constituents[];
766 };
767
768 /** Flags to indicate properties of receivers during memory region retrieval. */
769 typedef uint8_t ffa_memory_receiver_flags_t;
770
771 /**
772 * This corresponds to table 41 of the FF-A 1.0 EAC specification, "Memory
773 * access permissions descriptor".
774 */
775 struct ffa_memory_region_attributes {
776 /** The ID of the VM to which the memory is being given or shared. */
777 ffa_vm_id_t receiver;
778 /**
779 * The permissions with which the memory region should be mapped in the
780 * receiver's page table.
781 */
782 ffa_memory_access_permissions_t permissions;
783 /**
784 * Flags used during FFA_MEM_RETRIEVE_REQ and FFA_MEM_RETRIEVE_RESP
785 * for memory regions with multiple borrowers.
786 */
787 ffa_memory_receiver_flags_t flags;
788 };
789
790 /** Flags to control the behaviour of a memory sharing transaction. */
791 typedef uint32_t ffa_memory_region_flags_t;
792
793 /**
794 * Clear memory region contents after unmapping it from the sender and before
795 * mapping it for any receiver.
796 */
797 #define FFA_MEMORY_REGION_FLAG_CLEAR 0x1
798
799 /**
800 * Whether the hypervisor may time slice the memory sharing or retrieval
801 * operation.
802 */
803 #define FFA_MEMORY_REGION_FLAG_TIME_SLICE 0x2
804
805 /**
806 * Whether the hypervisor should clear the memory region after the receiver
807 * relinquishes it or is aborted.
808 */
809 #define FFA_MEMORY_REGION_FLAG_CLEAR_RELINQUISH 0x4
810
811 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_MASK ((0x3U) << 3)
812 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_UNSPECIFIED ((0x0U) << 3)
813 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_SHARE ((0x1U) << 3)
814 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_LEND ((0x2U) << 3)
815 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_DONATE ((0x3U) << 3)
816
817 #define FFA_MEMORY_REGION_ADDRESS_RANGE_HINT_VALID ((0x1U) << 9)
818 #define FFA_MEMORY_REGION_ADDRESS_RANGE_HINT_MASK ((0xFU) << 5)
819
820 /**
821 * This corresponds to table 42 of the FF-A 1.0 EAC specification, "Endpoint
822 * memory access descriptor".
823 */
824 struct ffa_memory_access {
825 struct ffa_memory_region_attributes receiver_permissions;
826 /**
827 * Offset in bytes from the start of the outer `ffa_memory_region` to
828 * an `ffa_composite_memory_region` struct.
829 */
830 uint32_t composite_memory_region_offset;
831 uint64_t reserved_0;
832 };
833
834 /** The maximum number of recipients a memory region may be sent to. */
835 #define MAX_MEM_SHARE_RECIPIENTS UINT32_C(2)
836
837 /**
838 * Information about a set of pages which are being shared. This corresponds to
839 * table 45 of the FF-A 1.0 EAC specification, "Lend, donate or share memory
840 * transaction descriptor". Note that it is also used for retrieve requests and
841 * responses.
842 */
843 struct ffa_memory_region {
844 /**
845 * The ID of the VM which originally sent the memory region, i.e. the
846 * owner.
847 */
848 ffa_vm_id_t sender;
849 ffa_memory_attributes_t attributes;
850 /** Reserved field, must be 0. */
851 uint8_t reserved_0;
852 /** Flags to control behaviour of the transaction. */
853 ffa_memory_region_flags_t flags;
854 ffa_memory_handle_t handle;
855 /**
856 * An implementation defined value associated with the receiver and the
857 * memory region.
858 */
859 uint64_t tag;
860 /** Reserved field, must be 0. */
861 uint32_t reserved_1;
862 /**
863 * The number of `ffa_memory_access` entries included in this
864 * transaction.
865 */
866 uint32_t receiver_count;
867 /**
868 * An array of `receiver_count` endpoint memory access descriptors.
869 * Each one specifies a memory region offset, an endpoint and the
870 * attributes with which this memory region should be mapped in that
871 * endpoint's page table.
872 */
873 struct ffa_memory_access receivers[];
874 };
875
876 /**
877 * Descriptor used for FFA_MEM_RELINQUISH requests. This corresponds to table
878 * 150 of the FF-A 1.0 EAC specification, "Descriptor to relinquish a memory
879 * region".
880 */
881 struct ffa_mem_relinquish {
882 ffa_memory_handle_t handle;
883 ffa_memory_region_flags_t flags;
884 uint32_t endpoint_count;
885 ffa_vm_id_t endpoints[];
886 };
887
888 /**
889 * Gets the `ffa_composite_memory_region` for the given receiver from an
890 * `ffa_memory_region`, or NULL if it is not valid.
891 */
892 static inline struct ffa_composite_memory_region *
ffa_memory_region_get_composite(struct ffa_memory_region * memory_region,uint32_t receiver_index)893 ffa_memory_region_get_composite(struct ffa_memory_region *memory_region,
894 uint32_t receiver_index)
895 {
896 uint32_t offset = memory_region->receivers[receiver_index]
897 .composite_memory_region_offset;
898
899 if (offset == 0) {
900 return NULL;
901 }
902
903 return (struct ffa_composite_memory_region *)((uint8_t *)memory_region +
904 offset);
905 }
906
ffa_mem_relinquish_init(struct ffa_mem_relinquish * relinquish_request,ffa_memory_handle_t handle,ffa_memory_region_flags_t flags,ffa_vm_id_t sender)907 static inline uint32_t ffa_mem_relinquish_init(
908 struct ffa_mem_relinquish *relinquish_request,
909 ffa_memory_handle_t handle, ffa_memory_region_flags_t flags,
910 ffa_vm_id_t sender)
911 {
912 relinquish_request->handle = handle;
913 relinquish_request->flags = flags;
914 relinquish_request->endpoint_count = 1;
915 relinquish_request->endpoints[0] = sender;
916 return sizeof(struct ffa_mem_relinquish) + sizeof(ffa_vm_id_t);
917 }
918
919 /**
920 * Endpoint RX/TX descriptor, as defined by Table 13.27 in FF-A v1.1 EAC0.
921 * It's used by the Hypervisor to describe the RX/TX buffers mapped by a VM
922 * to the SPMC, in order to allow indirect messaging.
923 */
924 struct ffa_endpoint_rx_tx_descriptor {
925 ffa_vm_id_t endpoint_id;
926 uint16_t reserved;
927
928 /*
929 * 8-byte aligned offset from the base address of this descriptor to the
930 * `ffa_composite_memory_region` describing the RX buffer.
931 */
932 uint32_t rx_offset;
933
934 /*
935 * 8-byte aligned offset from the base address of this descriptor to the
936 * `ffa_composite_memory_region` describing the TX buffer.
937 */
938 uint32_t tx_offset;
939
940 /* Pad to align on 16-byte boundary. */
941 uint32_t pad;
942 };
943
944 static inline struct ffa_composite_memory_region *
ffa_enpoint_get_rx_memory_region(struct ffa_endpoint_rx_tx_descriptor * desc)945 ffa_enpoint_get_rx_memory_region(struct ffa_endpoint_rx_tx_descriptor *desc)
946 {
947 return (struct ffa_composite_memory_region *)((uintptr_t)desc +
948 desc->rx_offset);
949 }
950
951 static inline struct ffa_composite_memory_region *
ffa_enpoint_get_tx_memory_region(struct ffa_endpoint_rx_tx_descriptor * desc)952 ffa_enpoint_get_tx_memory_region(struct ffa_endpoint_rx_tx_descriptor *desc)
953 {
954 return (struct ffa_composite_memory_region *)((uintptr_t)desc +
955 desc->tx_offset);
956 }
957
958 void ffa_memory_access_init_permissions(
959 struct ffa_memory_access *receiver, ffa_vm_id_t receiver_id,
960 enum ffa_data_access data_access,
961 enum ffa_instruction_access instruction_access,
962 ffa_memory_receiver_flags_t flags);
963 uint32_t ffa_memory_region_init_single_receiver(
964 struct ffa_memory_region *memory_region, size_t memory_region_max_size,
965 ffa_vm_id_t sender, ffa_vm_id_t receiver,
966 const struct ffa_memory_region_constituent constituents[],
967 uint32_t constituent_count, uint32_t tag,
968 ffa_memory_region_flags_t flags, enum ffa_data_access data_access,
969 enum ffa_instruction_access instruction_access,
970 enum ffa_memory_type type, enum ffa_memory_cacheability cacheability,
971 enum ffa_memory_shareability shareability, uint32_t *fragment_length,
972 uint32_t *total_length);
973 uint32_t ffa_memory_region_init(
974 struct ffa_memory_region *memory_region, size_t memory_region_max_size,
975 ffa_vm_id_t sender, struct ffa_memory_access receivers[],
976 uint32_t receiver_count,
977 const struct ffa_memory_region_constituent constituents[],
978 uint32_t constituent_count, uint32_t tag,
979 ffa_memory_region_flags_t flags, enum ffa_memory_type type,
980 enum ffa_memory_cacheability cacheability,
981 enum ffa_memory_shareability shareability, uint32_t *fragment_length,
982 uint32_t *total_length);
983 uint32_t ffa_memory_retrieve_request_init(
984 struct ffa_memory_region *memory_region, ffa_memory_handle_t handle,
985 ffa_vm_id_t sender, struct ffa_memory_access receivers[],
986 uint32_t receiver_count, uint32_t tag, ffa_memory_region_flags_t flags,
987 enum ffa_memory_type type, enum ffa_memory_cacheability cacheability,
988 enum ffa_memory_shareability shareability);
989 uint32_t ffa_memory_retrieve_request_init_single_receiver(
990 struct ffa_memory_region *memory_region, ffa_memory_handle_t handle,
991 ffa_vm_id_t sender, ffa_vm_id_t receiver, uint32_t tag,
992 ffa_memory_region_flags_t flags, enum ffa_data_access data_access,
993 enum ffa_instruction_access instruction_access,
994 enum ffa_memory_type type, enum ffa_memory_cacheability cacheability,
995 enum ffa_memory_shareability shareability);
996 uint32_t ffa_memory_lender_retrieve_request_init(
997 struct ffa_memory_region *memory_region, ffa_memory_handle_t handle,
998 ffa_vm_id_t sender);
999 bool ffa_retrieved_memory_region_init(
1000 struct ffa_memory_region *response, size_t response_max_size,
1001 ffa_vm_id_t sender, ffa_memory_attributes_t attributes,
1002 ffa_memory_region_flags_t flags, ffa_memory_handle_t handle,
1003 ffa_vm_id_t receiver, ffa_memory_access_permissions_t permissions,
1004 uint32_t page_count, uint32_t total_constituent_count,
1005 const struct ffa_memory_region_constituent constituents[],
1006 uint32_t fragment_constituent_count, uint32_t *total_length,
1007 uint32_t *fragment_length);
1008 uint32_t ffa_memory_fragment_init(
1009 struct ffa_memory_region_constituent *fragment,
1010 size_t fragment_max_size,
1011 const struct ffa_memory_region_constituent constituents[],
1012 uint32_t constituent_count, uint32_t *fragment_length);
1013 void ffa_endpoint_rx_tx_descriptor_init(
1014 struct ffa_endpoint_rx_tx_descriptor *desc, ffa_vm_id_t endpoint_id,
1015 uint64_t rx_address, uint64_t tx_address);
1016