blob: 812d81d3b176f7e9061e9414886751c51aea06af [file] [log] [blame]
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001/*
J-Alves13318e32021-02-22 17:21:00 +00002 * Copyright 2021 The Hafnium Authors.
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01003 *
Andrew Walbrane959ec12020-06-17 15:01:09 +01004 * 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.
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01007 */
8
9#pragma once
10
11#include "hf/types.h"
12
Karl Meakin0e617d92024-04-05 12:55:22 +010013/**
14 * The version number of a Firmware Framework implementation is a 31-bit
15 * unsigned integer, with the upper 15 bits denoting the major revision,
16 * and the lower 16 bits denoting the minor revision.
17 *
18 * See FF-A specification v1.2 ALP1, section 13.2.1.
19 */
20enum ffa_version {
21 FFA_VERSION_1_0 = 0x10000,
22 FFA_VERSION_1_1 = 0x10001,
23 FFA_VERSION_1_2 = 0x10002,
24 FFA_VERSION_COMPILED = FFA_VERSION_1_2,
25};
Daniel Boulby6e32c612021-02-17 15:09:41 +000026
Karl Meakin0e617d92024-04-05 12:55:22 +010027#define FFA_VERSION_MBZ_BIT (1U << 31U)
28#define FFA_VERSION_MAJOR_SHIFT (16U)
29#define FFA_VERSION_MAJOR_MASK (0x7FFFU)
30#define FFA_VERSION_MINOR_SHIFT (0U)
31#define FFA_VERSION_MINOR_MASK (0xFFFFU)
32
33/** Return true if the version is valid (i.e. bit 31 is 0). */
34static inline bool ffa_version_is_valid(uint32_t version)
35{
36 return (version & FFA_VERSION_MBZ_BIT) == 0;
37}
38
39/** Construct a version from a pair of major and minor components. */
40static inline enum ffa_version make_ffa_version(uint16_t major, uint16_t minor)
41{
42 return (enum ffa_version)((major << FFA_VERSION_MAJOR_SHIFT) |
43 (minor << FFA_VERSION_MINOR_SHIFT));
44}
45
46/** Get the major component of the version. */
47static inline uint16_t ffa_version_get_major(enum ffa_version version)
48{
49 return (version >> FFA_VERSION_MAJOR_SHIFT) & FFA_VERSION_MAJOR_MASK;
50}
51
52/** Get the minor component of the version. */
53static inline uint16_t ffa_version_get_minor(enum ffa_version version)
54{
55 return (version >> FFA_VERSION_MINOR_SHIFT) & FFA_VERSION_MINOR_MASK;
56}
Olivier Deprez62d99e32020-01-09 15:58:07 +010057
Daniel Boulbyc7dc9322023-10-27 15:12:07 +010058/**
59 * Check major versions are equal and the minor version of the caller is
60 * less than or equal to the minor version of the callee.
61 */
Karl Meakin0e617d92024-04-05 12:55:22 +010062static inline bool ffa_versions_are_compatible(enum ffa_version caller,
63 enum ffa_version callee)
64{
65 return ffa_version_get_major(caller) == ffa_version_get_major(callee) &&
66 ffa_version_get_minor(caller) <= ffa_version_get_minor(callee);
67}
Daniel Boulbyc7dc9322023-10-27 15:12:07 +010068
Andrew Walbranb5ab43c2020-04-30 11:32:54 +010069/* clang-format off */
70
71#define FFA_LOW_32_ID 0x84000060
72#define FFA_HIGH_32_ID 0x8400007F
73#define FFA_LOW_64_ID 0xC4000060
Fuad Tabbada72d142020-07-30 09:17:05 +010074#define FFA_HIGH_64_ID 0xC400007F
Andrew Walbranb5ab43c2020-04-30 11:32:54 +010075
Karl Meakinf51a35f2023-08-07 17:53:52 +010076/**
77 * FF-A function identifiers.
78 * Don't forget to update `ffa_func_name` if you add a new one.
79 */
J-Alves3829fc02021-03-18 12:49:18 +000080#define FFA_ERROR_32 0x84000060
81#define FFA_SUCCESS_32 0x84000061
82#define FFA_SUCCESS_64 0xC4000061
83#define FFA_INTERRUPT_32 0x84000062
84#define FFA_VERSION_32 0x84000063
85#define FFA_FEATURES_32 0x84000064
86#define FFA_RX_RELEASE_32 0x84000065
87#define FFA_RXTX_MAP_32 0x84000066
88#define FFA_RXTX_MAP_64 0xC4000066
89#define FFA_RXTX_UNMAP_32 0x84000067
90#define FFA_PARTITION_INFO_GET_32 0x84000068
91#define FFA_ID_GET_32 0x84000069
92#define FFA_MSG_POLL_32 0x8400006A /* Legacy FF-A v1.0 */
93#define FFA_MSG_WAIT_32 0x8400006B
94#define FFA_YIELD_32 0x8400006C
95#define FFA_RUN_32 0x8400006D
96#define FFA_MSG_SEND_32 0x8400006E /* Legacy FF-A v1.0 */
97#define FFA_MSG_SEND_DIRECT_REQ_32 0x8400006F
98#define FFA_MSG_SEND_DIRECT_REQ_64 0xC400006F
99#define FFA_MSG_SEND_DIRECT_RESP_32 0x84000070
100#define FFA_MSG_SEND_DIRECT_RESP_64 0xC4000070
101#define FFA_MEM_DONATE_32 0x84000071
J-Alves95fbb312024-03-20 15:19:16 +0000102#define FFA_MEM_DONATE_64 0xC4000071
J-Alves3829fc02021-03-18 12:49:18 +0000103#define FFA_MEM_LEND_32 0x84000072
J-Alves95fbb312024-03-20 15:19:16 +0000104#define FFA_MEM_LEND_64 0xC4000072
J-Alves3829fc02021-03-18 12:49:18 +0000105#define FFA_MEM_SHARE_32 0x84000073
J-Alves95fbb312024-03-20 15:19:16 +0000106#define FFA_MEM_SHARE_64 0xC4000073
J-Alves3829fc02021-03-18 12:49:18 +0000107#define FFA_MEM_RETRIEVE_REQ_32 0x84000074
J-Alves95fbb312024-03-20 15:19:16 +0000108#define FFA_MEM_RETRIEVE_REQ_64 0xC4000074
J-Alves3829fc02021-03-18 12:49:18 +0000109#define FFA_MEM_RETRIEVE_RESP_32 0x84000075
110#define FFA_MEM_RELINQUISH_32 0x84000076
111#define FFA_MEM_RECLAIM_32 0x84000077
112#define FFA_MEM_FRAG_RX_32 0x8400007A
113#define FFA_MEM_FRAG_TX_32 0x8400007B
114#define FFA_NORMAL_WORLD_RESUME 0x8400007C
115
116/* FF-A v1.1 */
117#define FFA_NOTIFICATION_BITMAP_CREATE_32 0x8400007D
118#define FFA_NOTIFICATION_BITMAP_DESTROY_32 0x8400007E
119#define FFA_NOTIFICATION_BIND_32 0x8400007F
120#define FFA_NOTIFICATION_UNBIND_32 0x84000080
121#define FFA_NOTIFICATION_SET_32 0x84000081
122#define FFA_NOTIFICATION_GET_32 0x84000082
123#define FFA_NOTIFICATION_INFO_GET_64 0xC4000083
124#define FFA_RX_ACQUIRE_32 0x84000084
125#define FFA_SPM_ID_GET_32 0x84000085
126#define FFA_MSG_SEND2_32 0x84000086
127#define FFA_SECONDARY_EP_REGISTER_64 0xC4000087
128#define FFA_MEM_PERM_GET_32 0x84000088
129#define FFA_MEM_PERM_SET_32 0x84000089
Raghu Krishnamurthyea6d25f2021-09-14 15:27:06 -0700130#define FFA_MEM_PERM_GET_64 0xC4000088
131#define FFA_MEM_PERM_SET_64 0xC4000089
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100132
Kathleen Capellae4fe2962023-09-01 17:08:47 -0400133/* FF-A v1.2 */
Maksims Svecovs71b76702022-05-20 15:32:58 +0100134#define FFA_CONSOLE_LOG_32 0x8400008A
135#define FFA_CONSOLE_LOG_64 0xC400008A
Raghu Krishnamurthy7592bcb2022-12-25 13:09:00 -0800136#define FFA_PARTITION_INFO_GET_REGS_64 0xC400008B
Madhukar Pappireddy77d3bcd2023-03-01 17:26:22 -0600137#define FFA_EL3_INTR_HANDLE_32 0x8400008C
Kathleen Capella41fea932023-06-23 17:39:28 -0400138#define FFA_MSG_SEND_DIRECT_REQ2_64 0xC400008D
Kathleen Capella087e5022023-09-07 18:04:15 -0400139#define FFA_MSG_SEND_DIRECT_RESP2_64 0xC400008E
Maksims Svecovs71b76702022-05-20 15:32:58 +0100140
Karl Meakinf51a35f2023-08-07 17:53:52 +0100141/**
142 * FF-A error codes.
143 * Don't forget to update `ffa_error_name` if you add a new one.
144 */
Karl Meakindc759f52024-05-07 16:08:02 +0100145enum ffa_error {
146 FFA_NOT_SUPPORTED = -1,
147 FFA_INVALID_PARAMETERS = -2,
148 FFA_NO_MEMORY = -3,
149 FFA_BUSY = -4,
150 FFA_INTERRUPTED = -5,
151 FFA_DENIED = -6,
152 FFA_RETRY = -7,
153 FFA_ABORTED = -8,
154 FFA_NO_DATA = -9,
155 FFA_NOT_READY = -10,
156};
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100157
158/* clang-format on */
159
Karl Meakinf51a35f2023-08-07 17:53:52 +0100160/* Return the name of the function identifier. */
161static inline const char *ffa_func_name(uint32_t func)
162{
163 switch (func) {
164 case FFA_ERROR_32:
165 return "FFA_ERROR_32";
166 case FFA_SUCCESS_32:
167 return "FFA_SUCCESS_32";
168 case FFA_SUCCESS_64:
169 return "FFA_SUCCESS_64";
170 case FFA_INTERRUPT_32:
171 return "FFA_INTERRUPT_32";
172 case FFA_VERSION_32:
173 return "FFA_VERSION_32";
174 case FFA_FEATURES_32:
175 return "FFA_FEATURES_32";
176 case FFA_RX_RELEASE_32:
177 return "FFA_RX_RELEASE_32";
178 case FFA_RXTX_MAP_32:
179 return "FFA_RXTX_MAP_32";
180 case FFA_RXTX_MAP_64:
181 return "FFA_RXTX_MAP_64";
182 case FFA_RXTX_UNMAP_32:
183 return "FFA_RXTX_UNMAP_32";
184 case FFA_PARTITION_INFO_GET_32:
185 return "FFA_PARTITION_INFO_GET_32";
186 case FFA_ID_GET_32:
187 return "FFA_ID_GET_32";
188 case FFA_MSG_POLL_32:
189 return "FFA_MSG_POLL_32";
190 case FFA_MSG_WAIT_32:
191 return "FFA_MSG_WAIT_32";
192 case FFA_YIELD_32:
193 return "FFA_YIELD_32";
194 case FFA_RUN_32:
195 return "FFA_RUN_32";
196 case FFA_MSG_SEND_32:
197 return "FFA_MSG_SEND_32";
198 case FFA_MSG_SEND_DIRECT_REQ_32:
199 return "FFA_MSG_SEND_DIRECT_REQ_32";
200 case FFA_MSG_SEND_DIRECT_REQ_64:
201 return "FFA_MSG_SEND_DIRECT_REQ_64";
202 case FFA_MSG_SEND_DIRECT_RESP_32:
203 return "FFA_MSG_SEND_DIRECT_RESP_32";
204 case FFA_MSG_SEND_DIRECT_RESP_64:
205 return "FFA_MSG_SEND_DIRECT_RESP_64";
206 case FFA_MEM_DONATE_32:
207 return "FFA_MEM_DONATE_32";
208 case FFA_MEM_LEND_32:
209 return "FFA_MEM_LEND_32";
210 case FFA_MEM_SHARE_32:
211 return "FFA_MEM_SHARE_32";
212 case FFA_MEM_RETRIEVE_REQ_32:
213 return "FFA_MEM_RETRIEVE_REQ_32";
J-Alves95fbb312024-03-20 15:19:16 +0000214 case FFA_MEM_DONATE_64:
215 return "FFA_MEM_DONATE_64";
216 case FFA_MEM_LEND_64:
217 return "FFA_MEM_LEND_64";
218 case FFA_MEM_SHARE_64:
219 return "FFA_MEM_SHARE_64";
220 case FFA_MEM_RETRIEVE_REQ_64:
221 return "FFA_MEM_RETRIEVE_REQ_64";
Karl Meakinf51a35f2023-08-07 17:53:52 +0100222 case FFA_MEM_RETRIEVE_RESP_32:
223 return "FFA_MEM_RETRIEVE_RESP_32";
224 case FFA_MEM_RELINQUISH_32:
225 return "FFA_MEM_RELINQUISH_32";
226 case FFA_MEM_RECLAIM_32:
227 return "FFA_MEM_RECLAIM_32";
228 case FFA_MEM_FRAG_RX_32:
229 return "FFA_MEM_FRAG_RX_32";
230 case FFA_MEM_FRAG_TX_32:
231 return "FFA_MEM_FRAG_TX_32";
232 case FFA_NORMAL_WORLD_RESUME:
233 return "FFA_NORMAL_WORLD_RESUME";
234
235 /* FF-A v1.1 */
236 case FFA_NOTIFICATION_BITMAP_CREATE_32:
237 return "FFA_NOTIFICATION_BITMAP_CREATE_32";
238 case FFA_NOTIFICATION_BITMAP_DESTROY_32:
239 return "FFA_NOTIFICATION_BITMAP_DESTROY_32";
240 case FFA_NOTIFICATION_BIND_32:
241 return "FFA_NOTIFICATION_BIND_32";
242 case FFA_NOTIFICATION_UNBIND_32:
243 return "FFA_NOTIFICATION_UNBIND_32";
244 case FFA_NOTIFICATION_SET_32:
245 return "FFA_NOTIFICATION_SET_32";
246 case FFA_NOTIFICATION_GET_32:
247 return "FFA_NOTIFICATION_GET_32";
248 case FFA_NOTIFICATION_INFO_GET_64:
249 return "FFA_NOTIFICATION_INFO_GET_64";
250 case FFA_RX_ACQUIRE_32:
251 return "FFA_RX_ACQUIRE_32";
252 case FFA_SPM_ID_GET_32:
253 return "FFA_SPM_ID_GET_32";
254 case FFA_MSG_SEND2_32:
255 return "FFA_MSG_SEND2_32";
256 case FFA_SECONDARY_EP_REGISTER_64:
257 return "FFA_SECONDARY_EP_REGISTER_64";
258 case FFA_MEM_PERM_GET_32:
259 return "FFA_MEM_PERM_GET_32";
260 case FFA_MEM_PERM_SET_32:
261 return "FFA_MEM_PERM_SET_32";
262 case FFA_MEM_PERM_GET_64:
263 return "FFA_MEM_PERM_GET_64";
264 case FFA_MEM_PERM_SET_64:
265 return "FFA_MEM_PERM_SET_64";
266
267 /* Implementation-defined ABIs. */
268 case FFA_CONSOLE_LOG_32:
269 return "FFA_CONSOLE_LOG_32";
270 case FFA_CONSOLE_LOG_64:
271 return "FFA_CONSOLE_LOG_64";
272 case FFA_PARTITION_INFO_GET_REGS_64:
273 return "FFA_PARTITION_INFO_GET_REGS_64";
274 case FFA_EL3_INTR_HANDLE_32:
275 return "FFA_EL3_INTR_HANDLE_32";
276
277 default:
278 return "UNKNOWN";
279 }
280}
281
282/* Return the name of the error code. */
Karl Meakindc759f52024-05-07 16:08:02 +0100283static inline const char *ffa_error_name(enum ffa_error error)
Karl Meakinf51a35f2023-08-07 17:53:52 +0100284{
285 switch (error) {
286 case FFA_NOT_SUPPORTED:
287 return "FFA_NOT_SUPPORTED";
288 case FFA_INVALID_PARAMETERS:
289 return "FFA_INVALID_PARAMETERS";
290 case FFA_NO_MEMORY:
291 return "FFA_NO_MEMORY";
292 case FFA_BUSY:
293 return "FFA_BUSY";
294 case FFA_INTERRUPTED:
295 return "FFA_INTERRUPTED";
296 case FFA_DENIED:
297 return "FFA_DENIED";
298 case FFA_RETRY:
299 return "FFA_RETRY";
300 case FFA_ABORTED:
301 return "FFA_ABORTED";
302 case FFA_NO_DATA:
303 return "FFA_NO_DATA";
Karl Meakindc759f52024-05-07 16:08:02 +0100304 case FFA_NOT_READY:
305 return "FFA_NOT_READY";
Karl Meakinf51a35f2023-08-07 17:53:52 +0100306 }
Karl Meakindc759f52024-05-07 16:08:02 +0100307 return "UNKNOWN";
Karl Meakinf51a35f2023-08-07 17:53:52 +0100308}
309
J-Alves6f72ca82021-11-01 12:34:58 +0000310/**
Karl Meakin49ec1e42024-05-10 13:08:24 +0100311 * Defined in Table 3.1 in the FF-A v.1.2 memory management supplement.
312 * Input properties:
313 * - Bits[31:2] and Bit[0] are reserved (SBZ).
314 * Output properties:
315 * - Bit[0]: dynamically allocated buffer support.
316 * - Bit[1]: NS bit handling.
317 * - Bit[2]: support for retrieval by hypervisor.
318 * - Bits[31:3] are reserved (MBZ).
J-Alves6f72ca82021-11-01 12:34:58 +0000319 */
Karl Meakin49ec1e42024-05-10 13:08:24 +0100320#define FFA_FEATURES_MEM_RETRIEVE_REQ_BUFFER_SUPPORT (0U << 0U)
321#define FFA_FEATURES_MEM_RETRIEVE_REQ_NS_SUPPORT (1U << 1U)
322#define FFA_FEATURES_MEM_RETRIEVE_REQ_HYPERVISOR_SUPPORT (1U << 2U)
J-Alves6f72ca82021-11-01 12:34:58 +0000323
Karl Meakin49ec1e42024-05-10 13:08:24 +0100324#define FFA_FEATURES_MEM_RETRIEVE_REQ_MBZ_HI_BIT (31U)
325#define FFA_FEATURES_MEM_RETRIEVE_REQ_MBZ_LO_BIT (2U)
326#define FFA_FEATURES_MEM_RETRIEVE_REQ_MBZ_BIT (0U)
J-Alves6f72ca82021-11-01 12:34:58 +0000327
Karl Meakin49ec1e42024-05-10 13:08:24 +0100328enum ffa_feature_id {
329 /* Query interrupt ID of Notification Pending Interrupt. */
330 FFA_FEATURE_NPI = 1,
Karl Meakin34b8ae92023-01-13 13:33:07 +0000331
Karl Meakin49ec1e42024-05-10 13:08:24 +0100332 /* Query interrupt ID of Schedule Receiver Interrupt. */
333 FFA_FEATURE_SRI = 2,
J-Alves6f72ca82021-11-01 12:34:58 +0000334
Karl Meakin49ec1e42024-05-10 13:08:24 +0100335 /* Query interrupt ID of the Managed Exit Interrupt. */
336 FFA_FEATURE_MEI = 3,
337};
J-Alves6f72ca82021-11-01 12:34:58 +0000338
Karl Meakin49ec1e42024-05-10 13:08:24 +0100339/** Constants for bitmasks used in FFA_FEATURES. */
340#define FFA_FEATURES_FEATURE_BIT (31U)
341#define FFA_FEATURES_FEATURE_MBZ_HI_BIT (30U)
342#define FFA_FEATURES_FEATURE_MBZ_LO_BIT (8U)
343
344#define FFA_FEATURES_NS_SUPPORT_BIT (1U)
J-Alves6f72ca82021-11-01 12:34:58 +0000345
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100346/* FF-A function specific constants. */
347#define FFA_MSG_RECV_BLOCK 0x1
348#define FFA_MSG_RECV_BLOCK_MASK 0x1
349
350#define FFA_MSG_SEND_NOTIFY 0x1
351#define FFA_MSG_SEND_NOTIFY_MASK 0x1
352
353#define FFA_MEM_RECLAIM_CLEAR 0x1
354
355#define FFA_SLEEP_INDEFINITE 0
356
Raghu Krishnamurthyea6d25f2021-09-14 15:27:06 -0700357#define FFA_MEM_PERM_RO UINT32_C(0x7)
358#define FFA_MEM_PERM_RW UINT32_C(0x5)
359#define FFA_MEM_PERM_RX UINT32_C(0x3)
360
Kathleen Capella7253bd52024-08-14 17:36:09 -0400361#define FFA_MSG_WAIT_FLAG_RETAIN_RX UINT32_C(0x1)
Daniel Boulbyb46cad12021-12-13 17:47:21 +0000362/*
Olivier Deprez013f4d62022-11-21 15:46:20 +0100363 * Defined in Table 13.34 in the FF-A v1.1 EAC0 specification.
Daniel Boulbyb46cad12021-12-13 17:47:21 +0000364 * The Partition count flag is used by FFA_PARTITION_INFO_GET to specify
365 * if partition info descriptors should be returned or just the count.
366 */
Olivier Deprez013f4d62022-11-21 15:46:20 +0100367#define FFA_PARTITION_COUNT_FLAG UINT32_C(0x1)
368#define FFA_PARTITION_COUNT_FLAG_MASK (UINT32_C(0x1) << 0)
Daniel Boulbyb46cad12021-12-13 17:47:21 +0000369
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100370/**
371 * For use where the FF-A specification refers explicitly to '4K pages'. Not to
372 * be confused with PAGE_SIZE, which is the translation granule Hafnium is
373 * configured to use.
374 */
J-Alves715d6232023-02-16 16:33:28 +0000375#define FFA_PAGE_SIZE ((size_t)4096)
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100376
Federico Recanatifc0295e2022-02-08 19:37:39 +0100377/** The ID of a VM. These are assigned sequentially starting with an offset. */
J-Alves19e20cf2023-08-02 12:48:55 +0100378typedef uint16_t ffa_id_t;
Federico Recanatifc0295e2022-02-08 19:37:39 +0100379
380/**
J-Alves661e1b72023-08-02 13:39:40 +0100381 * The FF-A v1.2 ALP0, section 6.1 defines that partition IDs are split into two
382 * parts:
383 * - Bit15 -> partition type identifier.
384 * - b'0 -> ID relates to a VM ID.
385 * - b'1 -> ID relates to an SP ID.
386 */
387#define FFA_ID_MASK ((ffa_id_t)0x8000)
388#define FFA_VM_ID_MASK ((ffa_id_t)0x0000)
389
390/**
391 * Helper to check if FF-A ID is a VM ID, managed by the hypervisor.
392 */
393static inline bool ffa_is_vm_id(ffa_id_t id)
394{
395 return (FFA_ID_MASK & id) == FFA_VM_ID_MASK;
396}
397
398/**
Federico Recanatifc0295e2022-02-08 19:37:39 +0100399 * Partition message header as specified by table 6.2 from FF-A v1.1 EAC0
400 * specification.
401 */
402struct ffa_partition_rxtx_header {
403 uint32_t flags; /* MBZ */
404 uint32_t reserved;
405 /* Offset from the beginning of the buffer to the message payload. */
406 uint32_t offset;
Karl Meakin9ca05512024-11-29 17:02:32 +0000407 /* Receiver endpoint ID. */
408 ffa_id_t receiver;
409 /* Sender endpoint ID. */
410 ffa_id_t sender;
Federico Recanatifc0295e2022-02-08 19:37:39 +0100411 /* Size of message in buffer. */
412 uint32_t size;
413};
414
415#define FFA_RXTX_HEADER_SIZE sizeof(struct ffa_partition_rxtx_header)
J-Alves70079932022-12-07 17:32:20 +0000416#define FFA_RXTX_ALLOCATOR_SHIFT 16
Federico Recanatifc0295e2022-02-08 19:37:39 +0100417
418static inline void ffa_rxtx_header_init(
J-Alves19e20cf2023-08-02 12:48:55 +0100419 ffa_id_t sender, ffa_id_t receiver, uint32_t size,
Federico Recanatifc0295e2022-02-08 19:37:39 +0100420 struct ffa_partition_rxtx_header *header)
421{
422 header->flags = 0;
423 header->reserved = 0;
424 header->offset = FFA_RXTX_HEADER_SIZE;
Karl Meakin9ca05512024-11-29 17:02:32 +0000425 header->sender = sender;
426 header->receiver = receiver;
Federico Recanatifc0295e2022-02-08 19:37:39 +0100427 header->size = size;
428}
429
Federico Recanatifc0295e2022-02-08 19:37:39 +0100430/* The maximum length possible for a single message. */
431#define FFA_PARTITION_MSG_PAYLOAD_MAX (HF_MAILBOX_SIZE - FFA_RXTX_HEADER_SIZE)
432
433struct ffa_partition_msg {
434 struct ffa_partition_rxtx_header header;
435 char payload[FFA_PARTITION_MSG_PAYLOAD_MAX];
436};
437
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100438/* The maximum length possible for a single message. */
439#define FFA_MSG_PAYLOAD_MAX HF_MAILBOX_SIZE
440
441enum ffa_data_access {
442 FFA_DATA_ACCESS_NOT_SPECIFIED,
443 FFA_DATA_ACCESS_RO,
444 FFA_DATA_ACCESS_RW,
445 FFA_DATA_ACCESS_RESERVED,
446};
447
Karl Meakinf98b2aa2023-10-12 16:09:59 +0100448static inline const char *ffa_data_access_name(enum ffa_data_access data_access)
449{
450 switch (data_access) {
451 case FFA_DATA_ACCESS_NOT_SPECIFIED:
452 return "FFA_DATA_ACCESS_NOT_SPECIFIED";
453 case FFA_DATA_ACCESS_RO:
454 return "FFA_DATA_ACCESS_RO";
455 case FFA_DATA_ACCESS_RW:
456 return "FFA_DATA_ACCESS_RW";
457 case FFA_DATA_ACCESS_RESERVED:
458 return "FFA_DATA_ACCESS_RESERVED";
459 }
460}
461
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100462enum ffa_instruction_access {
463 FFA_INSTRUCTION_ACCESS_NOT_SPECIFIED,
464 FFA_INSTRUCTION_ACCESS_NX,
465 FFA_INSTRUCTION_ACCESS_X,
466 FFA_INSTRUCTION_ACCESS_RESERVED,
467};
468
Karl Meakinf98b2aa2023-10-12 16:09:59 +0100469static inline const char *ffa_instruction_access_name(
470 enum ffa_instruction_access instruction_access)
471{
472 switch (instruction_access) {
473 case FFA_INSTRUCTION_ACCESS_NOT_SPECIFIED:
474 return "FFA_INSTRUCTION_ACCESS_NOT_SPECIFIED";
475 case FFA_INSTRUCTION_ACCESS_NX:
476 return "FFA_INSTRUCTION_ACCESS_NX";
477 case FFA_INSTRUCTION_ACCESS_X:
478 return "FFA_INSTRUCTION_ACCESS_X";
479 case FFA_INSTRUCTION_ACCESS_RESERVED:
480 return "FFA_INSTRUCTION_ACCESS_RESERVED";
481 }
482}
483
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100484enum ffa_memory_type {
485 FFA_MEMORY_NOT_SPECIFIED_MEM,
486 FFA_MEMORY_DEVICE_MEM,
487 FFA_MEMORY_NORMAL_MEM,
488};
489
Karl Meakinf98b2aa2023-10-12 16:09:59 +0100490static inline const char *ffa_memory_type_name(enum ffa_memory_type type)
491{
492 switch (type) {
493 case FFA_MEMORY_NOT_SPECIFIED_MEM:
494 return "FFA_MEMORY_NOT_SPECIFIED_MEM";
495 case FFA_MEMORY_DEVICE_MEM:
496 return "FFA_MEMORY_DEVICE_MEM";
497 case FFA_MEMORY_NORMAL_MEM:
498 return "FFA_MEMORY_NORMAL_MEM";
499 }
500}
501
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100502enum ffa_memory_cacheability {
503 FFA_MEMORY_CACHE_RESERVED = 0x0,
504 FFA_MEMORY_CACHE_NON_CACHEABLE = 0x1,
505 FFA_MEMORY_CACHE_RESERVED_1 = 0x2,
506 FFA_MEMORY_CACHE_WRITE_BACK = 0x3,
507 FFA_MEMORY_DEV_NGNRNE = 0x0,
508 FFA_MEMORY_DEV_NGNRE = 0x1,
509 FFA_MEMORY_DEV_NGRE = 0x2,
510 FFA_MEMORY_DEV_GRE = 0x3,
511};
512
Karl Meakinf98b2aa2023-10-12 16:09:59 +0100513static inline const char *ffa_memory_cacheability_name(
514 enum ffa_memory_cacheability cacheability)
515{
516 switch (cacheability) {
517 case FFA_MEMORY_CACHE_RESERVED:
518 return "FFA_MEMORY_CACHE_RESERVED";
519 case FFA_MEMORY_CACHE_NON_CACHEABLE:
520 return "FFA_MEMORY_CACHE_NON_CACHEABLE";
521 case FFA_MEMORY_CACHE_RESERVED_1:
522 return "FFA_MEMORY_CACHE_RESERVED_1";
523 case FFA_MEMORY_CACHE_WRITE_BACK:
524 return "FFA_MEMORY_CACHE_WRITE_BACK";
525 }
526}
527
Daniel Boulby9764ff62024-01-30 17:47:39 +0000528static inline const char *ffa_device_memory_cacheability_name(
529 enum ffa_memory_cacheability cacheability)
530{
531 switch (cacheability) {
532 case FFA_MEMORY_DEV_NGNRNE:
533 return "FFA_MEMORY_DEV_NGNRNE";
534 case FFA_MEMORY_DEV_NGNRE:
535 return "FFA_MEMORY_DEV_NGNRE";
536 case FFA_MEMORY_DEV_NGRE:
537 return "FFA_MEMORY_DEV_NGRE";
538 case FFA_MEMORY_DEV_GRE:
539 return "FFA_MEMORY_DEV_GRE";
540 }
541}
542
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100543enum ffa_memory_shareability {
544 FFA_MEMORY_SHARE_NON_SHAREABLE,
545 FFA_MEMORY_SHARE_RESERVED,
546 FFA_MEMORY_OUTER_SHAREABLE,
547 FFA_MEMORY_INNER_SHAREABLE,
548};
549
Karl Meakinf98b2aa2023-10-12 16:09:59 +0100550static inline const char *ffa_memory_shareability_name(
551 enum ffa_memory_shareability shareability)
552{
553 switch (shareability) {
554 case FFA_MEMORY_SHARE_NON_SHAREABLE:
555 return "FFA_MEMORY_SHARE_NON_SHAREABLE";
556 case FFA_MEMORY_SHARE_RESERVED:
557 return "FFA_MEMORY_SHARE_RESERVED";
558 case FFA_MEMORY_OUTER_SHAREABLE:
559 return "FFA_MEMORY_OUTER_SHAREABLE";
560 case FFA_MEMORY_INNER_SHAREABLE:
561 return "FFA_MEMORY_INNER_SHAREABLE";
562 }
563}
564
Olivier Deprez4342a3c2022-02-28 09:37:25 +0100565/**
566 * FF-A v1.1 REL0 Table 10.18 memory region attributes descriptor NS Bit 6.
567 * Per section 10.10.4.1, NS bit is reserved for FFA_MEM_DONATE/LEND/SHARE
568 * and FFA_MEM_RETRIEVE_REQUEST.
569 */
570enum ffa_memory_security {
571 FFA_MEMORY_SECURITY_UNSPECIFIED = 0,
572 FFA_MEMORY_SECURITY_SECURE = 0,
573 FFA_MEMORY_SECURITY_NON_SECURE,
574};
575
Karl Meakinf98b2aa2023-10-12 16:09:59 +0100576static inline const char *ffa_memory_security_name(
577 enum ffa_memory_security security)
578{
579 switch (security) {
580 case FFA_MEMORY_SECURITY_UNSPECIFIED:
581 return "FFA_MEMORY_SECURITY_UNSPECIFIED";
582 case FFA_MEMORY_SECURITY_NON_SECURE:
583 return "FFA_MEMORY_SECURITY_NON_SECURE";
584 }
585}
586
Karl Meakin84710f32023-10-12 15:14:49 +0100587typedef struct {
588 uint8_t data_access : 2;
589 uint8_t instruction_access : 2;
590} ffa_memory_access_permissions_t;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100591
592/**
J-Alves0b6653d2022-04-22 13:17:38 +0100593 * This corresponds to table 10.18 of the FF-A v1.1 EAC0 specification, "Memory
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100594 * region attributes descriptor".
595 */
Karl Meakin84710f32023-10-12 15:14:49 +0100596typedef struct {
597 uint8_t shareability : 2;
598 uint8_t cacheability : 2;
599 uint8_t type : 2;
600 uint8_t security : 2;
601 uint8_t : 8;
602} ffa_memory_attributes_t;
J-Alves0b6653d2022-04-22 13:17:38 +0100603
604/* FF-A v1.1 EAC0 states bit [15:7] Must Be Zero. */
605#define FFA_MEMORY_ATTRIBUTES_MBZ_MASK 0xFF80U
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100606
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100607/**
608 * A globally-unique ID assigned by the hypervisor for a region of memory being
609 * sent between VMs.
610 */
611typedef uint64_t ffa_memory_handle_t;
612
Karl Meakin1a760e72024-07-25 18:58:37 +0100613enum ffa_memory_handle_allocator {
614 FFA_MEMORY_HANDLE_ALLOCATOR_SPMC = 0,
615 FFA_MEMORY_HANDLE_ALLOCATOR_HYPERVISOR = 1,
616};
J-Alves917d2f22020-10-30 18:39:30 +0000617
Karl Meakin1a760e72024-07-25 18:58:37 +0100618#define FFA_MEMORY_HANDLE_ALLOCATOR_BIT UINT64_C(63)
619#define FFA_MEMORY_HANDLE_ALLOCATOR_MASK \
620 (UINT64_C(1) << FFA_MEMORY_HANDLE_ALLOCATOR_BIT)
J-Alves917d2f22020-10-30 18:39:30 +0000621#define FFA_MEMORY_HANDLE_INVALID (~UINT64_C(0))
622
Karl Meakin1a760e72024-07-25 18:58:37 +0100623static inline ffa_memory_handle_t ffa_memory_handle_make(
624 uint64_t index, enum ffa_memory_handle_allocator allocator)
625{
626 return index | ((uint64_t)allocator << FFA_MEMORY_HANDLE_ALLOCATOR_BIT);
627}
628
629static inline uint64_t ffa_memory_handle_index(ffa_memory_handle_t handle)
630{
631 return handle & ~FFA_MEMORY_HANDLE_ALLOCATOR_MASK;
632}
633
634static inline enum ffa_memory_handle_allocator ffa_memory_handle_allocator(
635 ffa_memory_handle_t handle)
636{
637 return ((handle & FFA_MEMORY_HANDLE_ALLOCATOR_MASK) != 0)
638 ? FFA_MEMORY_HANDLE_ALLOCATOR_HYPERVISOR
639 : FFA_MEMORY_HANDLE_ALLOCATOR_SPMC;
640}
641
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100642/**
643 * A count of VMs. This has the same range as the VM IDs but we give it a
644 * different name to make the different semantics clear.
645 */
J-Alves19e20cf2023-08-02 12:48:55 +0100646typedef ffa_id_t ffa_vm_count_t;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100647
648/** The index of a vCPU within a particular VM. */
649typedef uint16_t ffa_vcpu_index_t;
650
651/**
652 * A count of vCPUs. This has the same range as the vCPU indices but we give it
653 * a different name to make the different semantics clear.
654 */
655typedef ffa_vcpu_index_t ffa_vcpu_count_t;
656
657/** Parameter and return type of FF-A functions. */
658struct ffa_value {
659 uint64_t func;
660 uint64_t arg1;
661 uint64_t arg2;
662 uint64_t arg3;
663 uint64_t arg4;
664 uint64_t arg5;
665 uint64_t arg6;
666 uint64_t arg7;
Raghu Krishnamurthy567068e2022-12-26 07:46:38 -0800667
668 struct {
669 uint64_t arg8;
670 uint64_t arg9;
671 uint64_t arg10;
672 uint64_t arg11;
673 uint64_t arg12;
674 uint64_t arg13;
675 uint64_t arg14;
676 uint64_t arg15;
677 uint64_t arg16;
678 uint64_t arg17;
679 bool valid;
680 } extended_val;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100681};
682
Olivier Depreze562e542020-06-11 17:31:54 +0200683static inline uint32_t ffa_func_id(struct ffa_value args)
684{
685 return args.func;
686}
687
Karl Meakindc759f52024-05-07 16:08:02 +0100688static inline enum ffa_error ffa_error_code(struct ffa_value val)
J-Alves13318e32021-02-22 17:21:00 +0000689{
Karl Meakin66a38bd2024-05-28 16:00:56 +0100690 /* NOLINTNEXTLINE(EnumCastOutOfRange) */
Karl Meakindc759f52024-05-07 16:08:02 +0100691 return (enum ffa_error)val.arg2;
J-Alves13318e32021-02-22 17:21:00 +0000692}
693
J-Alves19e20cf2023-08-02 12:48:55 +0100694static inline ffa_id_t ffa_sender(struct ffa_value args)
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100695{
696 return (args.arg1 >> 16) & 0xffff;
697}
698
J-Alves19e20cf2023-08-02 12:48:55 +0100699static inline ffa_id_t ffa_receiver(struct ffa_value args)
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100700{
701 return args.arg1 & 0xffff;
702}
703
704static inline uint32_t ffa_msg_send_size(struct ffa_value args)
705{
706 return args.arg3;
707}
708
Federico Recanati25053ee2022-03-14 15:01:53 +0100709static inline uint32_t ffa_msg_send2_flags(struct ffa_value args)
710{
711 return args.arg2;
712}
713
Olivier Depreze562e542020-06-11 17:31:54 +0200714static inline uint32_t ffa_partition_info_get_count(struct ffa_value args)
715{
716 return args.arg2;
717}
718
Raghu Krishnamurthy2957b922022-12-27 10:29:12 -0800719static inline uint16_t ffa_partition_info_regs_get_last_idx(
720 struct ffa_value args)
721{
722 return args.arg2 & 0xFFFF;
723}
724
725static inline uint16_t ffa_partition_info_regs_get_curr_idx(
726 struct ffa_value args)
727{
728 return (args.arg2 >> 16) & 0xFFFF;
729}
730
731static inline uint16_t ffa_partition_info_regs_get_tag(struct ffa_value args)
732{
733 return (args.arg2 >> 32) & 0xFFFF;
734}
735
736static inline uint16_t ffa_partition_info_regs_get_desc_size(
737 struct ffa_value args)
738{
739 return (args.arg2 >> 48);
740}
741
Andrew Walbran1bbe9402020-04-30 16:47:13 +0100742static inline ffa_memory_handle_t ffa_assemble_handle(uint32_t a1, uint32_t a2)
743{
744 return (uint64_t)a1 | (uint64_t)a2 << 32;
745}
746
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100747static inline ffa_memory_handle_t ffa_mem_success_handle(struct ffa_value args)
748{
Andrew Walbran1bbe9402020-04-30 16:47:13 +0100749 return ffa_assemble_handle(args.arg2, args.arg3);
750}
751
Andrew Walbranca808b12020-05-15 17:22:28 +0100752static inline ffa_memory_handle_t ffa_frag_handle(struct ffa_value args)
753{
754 return ffa_assemble_handle(args.arg1, args.arg2);
755}
756
Andrew Walbran1bbe9402020-04-30 16:47:13 +0100757static inline struct ffa_value ffa_mem_success(ffa_memory_handle_t handle)
758{
759 return (struct ffa_value){.func = FFA_SUCCESS_32,
760 .arg2 = (uint32_t)handle,
761 .arg3 = (uint32_t)(handle >> 32)};
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100762}
763
J-Alves19e20cf2023-08-02 12:48:55 +0100764static inline ffa_id_t ffa_vm_id(struct ffa_value args)
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100765{
766 return (args.arg1 >> 16) & 0xffff;
767}
768
769static inline ffa_vcpu_index_t ffa_vcpu_index(struct ffa_value args)
770{
771 return args.arg1 & 0xffff;
772}
773
J-Alves19e20cf2023-08-02 12:48:55 +0100774static inline uint64_t ffa_vm_vcpu(ffa_id_t vm_id, ffa_vcpu_index_t vcpu_index)
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100775{
776 return ((uint32_t)vm_id << 16) | vcpu_index;
777}
778
J-Alves19e20cf2023-08-02 12:48:55 +0100779static inline ffa_id_t ffa_frag_sender(struct ffa_value args)
Andrew Walbranca808b12020-05-15 17:22:28 +0100780{
781 return (args.arg4 >> 16) & 0xffff;
782}
783
J-Alves6f72ca82021-11-01 12:34:58 +0000784static inline uint32_t ffa_feature_intid(struct ffa_value args)
785{
786 return (uint32_t)args.arg2;
787}
788
Karl Meakind0356f82024-09-04 13:34:31 +0100789#define FFA_FRAMEWORK_MSG_BIT (UINT64_C(1) << 31)
790#define FFA_FRAMEWORK_MSG_FUNC_MASK UINT64_C(0xFF)
791
792/**
793 * Identifies the VM availability message. See section 18.3 of v1.2 FF-A
794 * specification.
795 */
796enum ffa_framework_msg_func {
797 FFA_FRAMEWORK_MSG_VM_CREATION_REQ = 4,
798 FFA_FRAMEWORK_MSG_VM_CREATION_RESP = 5,
799
800 FFA_FRAMEWORK_MSG_VM_DESTRUCTION_REQ = 6,
801 FFA_FRAMEWORK_MSG_VM_DESTRUCTION_RESP = 7,
802};
803
Karl Meakin06e8b732024-09-20 18:26:49 +0100804#define FFA_VM_AVAILABILITY_MESSAGE_SBZ_LO 16
805#define FFA_VM_AVAILABILITY_MESSAGE_SBZ_HI 31
806
Karl Meakind0356f82024-09-04 13:34:31 +0100807/** Get the `flags` field of a framework message */
808static inline uint32_t ffa_framework_msg_flags(struct ffa_value args)
Daniel Boulbyefa381f2022-01-18 14:49:40 +0000809{
810 return (uint32_t)args.arg2;
811}
812
Karl Meakind0356f82024-09-04 13:34:31 +0100813/** Is `args` a framework message? */
814static inline bool ffa_is_framework_msg(struct ffa_value args)
815{
Karl Meakin06e8b732024-09-20 18:26:49 +0100816 return (args.func != FFA_MSG_SEND_DIRECT_REQ2_64) &&
817 (args.func != FFA_MSG_SEND_DIRECT_RESP2_64) &&
818 ((ffa_framework_msg_flags(args) & FFA_FRAMEWORK_MSG_BIT) != 0);
Karl Meakind0356f82024-09-04 13:34:31 +0100819}
820
Karl Meakina1a02352024-09-20 18:27:18 +0100821/**
822 * Get the ID of the VM that has been created/destroyed from VM availability
823 * message
824 */
825static inline ffa_id_t ffa_vm_availability_message_vm_id(struct ffa_value args)
826{
827 return args.arg5 & 0xFFFF;
828}
829
Karl Meakind0356f82024-09-04 13:34:31 +0100830/** Get the function ID from a framework message */
831static inline uint32_t ffa_framework_msg_func(struct ffa_value args)
832{
833 return ffa_framework_msg_flags(args) & FFA_FRAMEWORK_MSG_FUNC_MASK;
834}
835
Andrew Walbranb5ab43c2020-04-30 11:32:54 +0100836/**
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100837 * Holds the UUID in a struct that is mappable directly to the SMCC calling
838 * convention, which is used for FF-A calls.
839 *
840 * Refer to table 84 of the FF-A 1.0 EAC specification as well as section 5.3
841 * of the SMCC Spec 1.2.
842 */
843struct ffa_uuid {
844 uint32_t uuid[4];
845};
846
847static inline void ffa_uuid_init(uint32_t w0, uint32_t w1, uint32_t w2,
848 uint32_t w3, struct ffa_uuid *uuid)
849{
850 uuid->uuid[0] = w0;
851 uuid->uuid[1] = w1;
852 uuid->uuid[2] = w2;
853 uuid->uuid[3] = w3;
854}
855
856static inline bool ffa_uuid_equal(const struct ffa_uuid *uuid1,
857 const struct ffa_uuid *uuid2)
858{
859 return (uuid1->uuid[0] == uuid2->uuid[0]) &&
860 (uuid1->uuid[1] == uuid2->uuid[1]) &&
861 (uuid1->uuid[2] == uuid2->uuid[2]) &&
862 (uuid1->uuid[3] == uuid2->uuid[3]);
863}
864
865static inline bool ffa_uuid_is_null(const struct ffa_uuid *uuid)
866{
Karl Meakin60532972024-08-02 16:11:21 +0100867 struct ffa_uuid null = {0};
868
869 return ffa_uuid_equal(uuid, &null);
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100870}
871
Karl Meakin9478e322024-09-23 17:47:09 +0100872static inline void ffa_uuid_from_u64x2(uint64_t uuid_lo, uint64_t uuid_hi,
873 struct ffa_uuid *uuid)
Kathleen Capella41fea932023-06-23 17:39:28 -0400874{
875 ffa_uuid_init((uint32_t)(uuid_lo & 0xFFFFFFFFU),
876 (uint32_t)(uuid_lo >> 32),
877 (uint32_t)(uuid_hi & 0xFFFFFFFFU),
878 (uint32_t)(uuid_hi >> 32), uuid);
879}
Karl Meakin9478e322024-09-23 17:47:09 +0100880
881/**
882 * Split `uuid` into two u64s.
883 * This function writes to pointer parameters because C does not allow returning
884 * arrays from functions.
885 */
886static inline void ffa_uuid_to_u64x2(uint64_t *lo, uint64_t *hi,
887 const struct ffa_uuid *uuid)
888{
889 *lo = (uint64_t)uuid->uuid[1] << 32 | uuid->uuid[0];
890 *hi = (uint64_t)uuid->uuid[3] << 32 | uuid->uuid[2];
891}
892
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100893/**
894 * Flags to determine the partition properties, as required by
895 * FFA_PARTITION_INFO_GET.
896 *
Kathleen Capellaf71dee42023-08-08 16:24:14 -0400897 * The values of the flags are specified in table 6.2 of DEN0077A FF-A 1.2 ALP0
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100898 * specification, "Partition information descriptor, partition properties".
899 */
900typedef uint32_t ffa_partition_properties_t;
901
Kathleen Capellaf71dee42023-08-08 16:24:14 -0400902/**
903 * Partition property: partition supports receipt of direct requests via the
904 * FFA_MSG_SEND_DIRECT_REQ ABI.
905 */
Kathleen Capella402fa852022-11-09 16:16:51 -0500906#define FFA_PARTITION_DIRECT_REQ_RECV (UINT32_C(1) << 0)
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100907
Kathleen Capellaf71dee42023-08-08 16:24:14 -0400908/**
909 * Partition property: partition can send direct requests via the
910 * FFA_MSG_SEND_DIRECT_REQ ABI.
911 */
Kathleen Capella402fa852022-11-09 16:16:51 -0500912#define FFA_PARTITION_DIRECT_REQ_SEND (UINT32_C(1) << 1)
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100913
914/** Partition property: partition can send and receive indirect messages. */
Kathleen Capella402fa852022-11-09 16:16:51 -0500915#define FFA_PARTITION_INDIRECT_MSG (UINT32_C(1) << 2)
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100916
J-Alves09ff9d82021-11-02 11:55:20 +0000917/** Partition property: partition can receive notifications. */
Kathleen Capella402fa852022-11-09 16:16:51 -0500918#define FFA_PARTITION_NOTIFICATION (UINT32_C(1) << 3)
919
Karl Meakina603e082024-08-02 17:57:27 +0100920/**
921 * Partition property: partition must be informed about each VM that is created
922 * by the Hypervisor.
923 */
924#define FFA_PARTITION_VM_CREATED (UINT32_C(1) << 6)
925
926/**
927 * Partition property: partition must be informed about each VM that is
928 * destroyed by the Hypervisor.
929 */
930#define FFA_PARTITION_VM_DESTROYED (UINT32_C(1) << 7)
931
Kathleen Capella402fa852022-11-09 16:16:51 -0500932/** Partition property: partition runs in the AArch64 execution state. */
933#define FFA_PARTITION_AARCH64_EXEC (UINT32_C(1) << 8)
J-Alves09ff9d82021-11-02 11:55:20 +0000934
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100935/**
Kathleen Capellaf71dee42023-08-08 16:24:14 -0400936 * Partition property: partition supports receipt of direct requests via the
937 * FFA_MSG_SEND_DIRECT_REQ2 ABI.
938 */
939#define FFA_PARTITION_DIRECT_REQ2_RECV (UINT32_C(1) << 9)
940
941/**
942 * Partition property: partition can send direct requests via the
943 * FFA_MSG_SEND_DIRECT_REQ2 ABI.
944 */
945#define FFA_PARTITION_DIRECT_REQ2_SEND (UINT32_C(1) << 10)
946
947/**
Fuad Tabbae4efcc32020-07-16 15:37:27 +0100948 * Holds information returned for each partition by the FFA_PARTITION_INFO_GET
949 * interface.
Kathleen Capella402fa852022-11-09 16:16:51 -0500950 * This corresponds to table 13.37 "Partition information descriptor"
951 * in FF-A 1.1 EAC0 specification.
Daniel Boulby1ddb3d72021-12-16 18:16:50 +0000952 */
953struct ffa_partition_info {
J-Alves19e20cf2023-08-02 12:48:55 +0100954 ffa_id_t vm_id;
Daniel Boulby1ddb3d72021-12-16 18:16:50 +0000955 ffa_vcpu_count_t vcpu_count;
956 ffa_partition_properties_t properties;
957 struct ffa_uuid uuid;
958};
959
J-Alvesdd1ad572022-01-25 17:58:26 +0000960/** Length in bytes of the name in boot information descriptor. */
961#define FFA_BOOT_INFO_NAME_LEN 16
962
J-Alves240d84c2022-04-22 12:19:34 +0100963/**
964 * The FF-A boot info descriptor, as defined in table 5.8 of section 5.4.1, of
965 * the FF-A v1.1 EAC0 specification.
966 */
J-Alvesdd1ad572022-01-25 17:58:26 +0000967struct ffa_boot_info_desc {
968 char name[FFA_BOOT_INFO_NAME_LEN];
969 uint8_t type;
970 uint8_t reserved;
971 uint16_t flags;
972 uint32_t size;
973 uint64_t content;
974};
975
976/** FF-A boot information type mask. */
977#define FFA_BOOT_INFO_TYPE_SHIFT 7
978#define FFA_BOOT_INFO_TYPE_MASK (0x1U << FFA_BOOT_INFO_TYPE_SHIFT)
979#define FFA_BOOT_INFO_TYPE_STD 0U
980#define FFA_BOOT_INFO_TYPE_IMPDEF 1U
981
982/** Standard boot info type IDs. */
983#define FFA_BOOT_INFO_TYPE_ID_MASK 0x7FU
984#define FFA_BOOT_INFO_TYPE_ID_FDT 0U
985#define FFA_BOOT_INFO_TYPE_ID_HOB 1U
986
987/** FF-A Boot Info descriptors flags. */
988#define FFA_BOOT_INFO_FLAG_MBZ_MASK 0xFFF0U
989
990/** Bits [1:0] encode the format of the name field in ffa_boot_info_desc. */
991#define FFA_BOOT_INFO_FLAG_NAME_FORMAT_SHIFT 0U
992#define FFA_BOOT_INFO_FLAG_NAME_FORMAT_MASK \
993 (0x3U << FFA_BOOT_INFO_FLAG_NAME_FORMAT_SHIFT)
994#define FFA_BOOT_INFO_FLAG_NAME_FORMAT_STRING 0x0U
995#define FFA_BOOT_INFO_FLAG_NAME_FORMAT_UUID 0x1U
996
997/** Bits [3:2] encode the format of the content field in ffa_boot_info_desc. */
998#define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_SHIFT 2
999#define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_MASK \
1000 (0x3U << FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_SHIFT)
1001#define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_VALUE 0x1U
1002#define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_ADDR 0x0U
1003
1004static inline uint16_t ffa_boot_info_content_format(
1005 struct ffa_boot_info_desc *desc)
1006{
1007 return (desc->flags & FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_MASK) >>
1008 FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_SHIFT;
1009}
1010
1011static inline uint16_t ffa_boot_info_name_format(
1012 struct ffa_boot_info_desc *desc)
1013{
1014 return (desc->flags & FFA_BOOT_INFO_FLAG_NAME_FORMAT_MASK) >>
1015 FFA_BOOT_INFO_FLAG_NAME_FORMAT_SHIFT;
1016}
1017
1018static inline uint8_t ffa_boot_info_type_id(struct ffa_boot_info_desc *desc)
1019{
1020 return desc->type & FFA_BOOT_INFO_TYPE_ID_MASK;
1021}
1022
1023static inline uint8_t ffa_boot_info_type(struct ffa_boot_info_desc *desc)
1024{
1025 return (desc->type & FFA_BOOT_INFO_TYPE_MASK) >>
1026 FFA_BOOT_INFO_TYPE_SHIFT;
1027}
1028
1029/** Length in bytes of the signature in the boot descriptor. */
1030#define FFA_BOOT_INFO_HEADER_SIGNATURE_LEN 4
1031
J-Alves240d84c2022-04-22 12:19:34 +01001032/**
1033 * The FF-A boot information header, as defined in table 5.9 of section 5.4.2,
1034 * of the FF-A v1.1 EAC0 specification.
1035 */
J-Alvesdd1ad572022-01-25 17:58:26 +00001036struct ffa_boot_info_header {
1037 uint32_t signature;
1038 uint32_t version;
1039 uint32_t info_blob_size;
1040 uint32_t desc_size;
1041 uint32_t desc_count;
1042 uint32_t desc_offset;
1043 uint64_t reserved;
1044 struct ffa_boot_info_desc boot_info[];
1045};
1046
Fuad Tabbae4efcc32020-07-16 15:37:27 +01001047/**
J-Alves980d1992021-03-18 12:49:18 +00001048 * FF-A v1.1 specification restricts the number of notifications to a maximum
1049 * of 64. Following all possible bitmaps.
1050 */
Karl Meakin2ad6b662024-07-29 20:45:40 +01001051#define FFA_NOTIFICATION_MASK(ID) (UINT64_C(1) << (ID))
J-Alves980d1992021-03-18 12:49:18 +00001052
1053typedef uint64_t ffa_notifications_bitmap_t;
1054
1055#define MAX_FFA_NOTIFICATIONS 64U
1056
1057/**
J-Alvesc003a7a2021-03-18 13:06:53 +00001058 * Flag for notification bind and set, to specify call is about per-vCPU
1059 * notifications.
1060 */
Olivier Deprezb76307d2022-06-09 17:17:45 +02001061#define FFA_NOTIFICATION_FLAG_PER_VCPU (UINT32_C(1) << 0)
J-Alvesc003a7a2021-03-18 13:06:53 +00001062
Federico Recanatie73d2832022-04-20 11:10:52 +02001063#define FFA_NOTIFICATION_SPM_BUFFER_FULL_MASK FFA_NOTIFICATION_MASK(0)
1064#define FFA_NOTIFICATION_HYP_BUFFER_FULL_MASK FFA_NOTIFICATION_MASK(32)
1065
1066/**
1067 * Helper functions to check for buffer full notification.
1068 */
1069static inline bool is_ffa_hyp_buffer_full_notification(
1070 ffa_notifications_bitmap_t framework)
1071{
1072 return (framework & FFA_NOTIFICATION_HYP_BUFFER_FULL_MASK) != 0;
1073}
1074
1075static inline bool is_ffa_spm_buffer_full_notification(
1076 ffa_notifications_bitmap_t framework)
1077{
1078 return (framework & FFA_NOTIFICATION_SPM_BUFFER_FULL_MASK) != 0;
1079}
1080
J-Alvesc003a7a2021-03-18 13:06:53 +00001081/**
J-Alves980d1992021-03-18 12:49:18 +00001082 * Helper function to assemble a 64-bit sized bitmap, from the 32-bit sized lo
1083 * and hi.
1084 * Helpful as FF-A specification defines that the notifications interfaces
1085 * arguments are 32-bit registers.
1086 */
1087static inline ffa_notifications_bitmap_t ffa_notifications_bitmap(uint32_t lo,
1088 uint32_t hi)
1089{
1090 return (ffa_notifications_bitmap_t)hi << 32U | lo;
1091}
1092
J-Alves98ff9562021-09-09 14:39:41 +01001093static inline ffa_notifications_bitmap_t ffa_notification_get_from_sp(
1094 struct ffa_value val)
1095{
1096 return ffa_notifications_bitmap((uint32_t)val.arg2, (uint32_t)val.arg3);
1097}
1098
1099static inline ffa_notifications_bitmap_t ffa_notification_get_from_vm(
1100 struct ffa_value val)
1101{
1102 return ffa_notifications_bitmap((uint32_t)val.arg4, (uint32_t)val.arg5);
1103}
1104
Federico Recanatie73d2832022-04-20 11:10:52 +02001105static inline ffa_notifications_bitmap_t ffa_notification_get_from_framework(
1106 struct ffa_value val)
1107{
1108 return ffa_notifications_bitmap((uint32_t)val.arg6, (uint32_t)val.arg7);
1109}
1110
Karl Meakinf9c73ce2024-07-30 17:37:13 +01001111typedef uint32_t ffa_notification_flags_t;
1112
1113/** Flags used in calls to FFA_NOTIFICATION_BIND interface. */
1114#define FFA_NOTIFICATIONS_FLAG_PER_VCPU (UINT32_C(1) << 0)
1115
1116/** Flags used in calls to FFA_NOTIFICATION_GET interface. */
Olivier Deprezb76307d2022-06-09 17:17:45 +02001117#define FFA_NOTIFICATION_FLAG_BITMAP_SP (UINT32_C(1) << 0)
1118#define FFA_NOTIFICATION_FLAG_BITMAP_VM (UINT32_C(1) << 1)
1119#define FFA_NOTIFICATION_FLAG_BITMAP_SPM (UINT32_C(1) << 2)
1120#define FFA_NOTIFICATION_FLAG_BITMAP_HYP (UINT32_C(1) << 3)
J-Alvesaa79c012021-07-09 14:29:45 +01001121
Karl Meakinf9c73ce2024-07-30 17:37:13 +01001122/** Flags used in calls to FFA_NOTIFICATION_SET interface. */
Olivier Deprezb76307d2022-06-09 17:17:45 +02001123#define FFA_NOTIFICATIONS_FLAG_PER_VCPU (UINT32_C(1) << 0)
Olivier Deprezb76307d2022-06-09 17:17:45 +02001124#define FFA_NOTIFICATIONS_FLAG_DELAY_SRI (UINT32_C(1) << 1)
Olivier Deprezb76307d2022-06-09 17:17:45 +02001125#define FFA_NOTIFICATIONS_FLAGS_VCPU_ID(id) \
1126 ((((uint32_t)(id)) & UINT32_C(0xffff)) << 16)
Karl Meakinf9c73ce2024-07-30 17:37:13 +01001127#define FFA_NOTIFICATIONS_FLAGS_GET_VCPU_ID(flags) \
1128 ((ffa_vcpu_index_t)((flags) >> 16))
J-Alves13394022021-06-30 13:48:49 +01001129
J-Alvesbe6e3032021-11-30 14:54:12 +00001130static inline ffa_vcpu_index_t ffa_notifications_get_vcpu(struct ffa_value args)
J-Alvesaa79c012021-07-09 14:29:45 +01001131{
Karl Meakinf9c73ce2024-07-30 17:37:13 +01001132 return FFA_NOTIFICATIONS_FLAGS_GET_VCPU_ID(args.arg1);
J-Alvesaa79c012021-07-09 14:29:45 +01001133}
1134
1135/**
J-Alvesc8e8a222021-06-08 17:33:52 +01001136 * The max number of IDs for return of FFA_NOTIFICATION_INFO_GET.
1137 */
1138#define FFA_NOTIFICATIONS_INFO_GET_MAX_IDS 20U
1139
1140/**
1141 * Number of registers to use in successfull return of interface
1142 * FFA_NOTIFICATION_INFO_GET.
1143 */
1144#define FFA_NOTIFICATIONS_INFO_GET_REGS_RET 5U
1145
1146#define FFA_NOTIFICATIONS_INFO_GET_FLAG_MORE_PENDING 0x1U
1147
1148/**
1149 * Helper macros for return parameter encoding as described in section 17.7.1
1150 * of the FF-A v1.1 Beta0 specification.
1151 */
1152#define FFA_NOTIFICATIONS_LISTS_COUNT_SHIFT 0x7U
1153#define FFA_NOTIFICATIONS_LISTS_COUNT_MASK 0x1fU
Karl Meakin2ad6b662024-07-29 20:45:40 +01001154#define FFA_NOTIFICATIONS_LIST_SHIFT(l) (2 * ((l) - 1) + 12)
J-Alvesc8e8a222021-06-08 17:33:52 +01001155#define FFA_NOTIFICATIONS_LIST_SIZE_MASK 0x3U
Daniel Boulby1308a632024-09-11 15:19:16 +01001156#define FFA_NOTIFICATIONS_LIST_MAX_SIZE 0x4U
J-Alvesc8e8a222021-06-08 17:33:52 +01001157
1158static inline uint32_t ffa_notification_info_get_lists_count(
1159 struct ffa_value args)
1160{
1161 return (uint32_t)(args.arg2 >> FFA_NOTIFICATIONS_LISTS_COUNT_SHIFT) &
1162 FFA_NOTIFICATIONS_LISTS_COUNT_MASK;
1163}
1164
1165static inline uint32_t ffa_notification_info_get_list_size(
1166 struct ffa_value args, unsigned int list_idx)
1167{
1168 return ((uint32_t)args.arg2 >> FFA_NOTIFICATIONS_LIST_SHIFT(list_idx)) &
1169 FFA_NOTIFICATIONS_LIST_SIZE_MASK;
1170}
1171
1172static inline bool ffa_notification_info_get_more_pending(struct ffa_value args)
1173{
1174 return (args.arg2 & FFA_NOTIFICATIONS_INFO_GET_FLAG_MORE_PENDING) != 0U;
1175}
1176
Daniel Boulby1308a632024-09-11 15:19:16 +01001177void ffa_notification_info_get_and_check(
1178 const uint32_t expected_lists_count,
1179 const uint32_t *const expected_lists_sizes,
1180 const uint16_t *const expected_ids);
1181
J-Alvesc8e8a222021-06-08 17:33:52 +01001182/**
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001183 * A set of contiguous pages which is part of a memory region. This corresponds
J-Alves0b6653d2022-04-22 13:17:38 +01001184 * to table 10.14 of the FF-A v1.1 EAC0 specification, "Constituent memory
1185 * region descriptor".
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001186 */
1187struct ffa_memory_region_constituent {
1188 /**
1189 * The base IPA of the constituent memory region, aligned to 4 kiB page
1190 * size granularity.
1191 */
1192 uint64_t address;
1193 /** The number of 4 kiB pages in the constituent memory region. */
1194 uint32_t page_count;
1195 /** Reserved field, must be 0. */
1196 uint32_t reserved;
1197};
1198
1199/**
J-Alves0b6653d2022-04-22 13:17:38 +01001200 * A set of pages comprising a memory region. This corresponds to table 10.13 of
1201 * the FF-A v1.1 EAC0 specification, "Composite memory region descriptor".
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001202 */
1203struct ffa_composite_memory_region {
1204 /**
1205 * The total number of 4 kiB pages included in this memory region. This
1206 * must be equal to the sum of page counts specified in each
1207 * `ffa_memory_region_constituent`.
1208 */
1209 uint32_t page_count;
1210 /**
1211 * The number of constituents (`ffa_memory_region_constituent`)
1212 * included in this memory region range.
1213 */
1214 uint32_t constituent_count;
1215 /** Reserved field, must be 0. */
1216 uint64_t reserved_0;
1217 /** An array of `constituent_count` memory region constituents. */
1218 struct ffa_memory_region_constituent constituents[];
1219};
1220
1221/** Flags to indicate properties of receivers during memory region retrieval. */
1222typedef uint8_t ffa_memory_receiver_flags_t;
1223
1224/**
J-Alves0b6653d2022-04-22 13:17:38 +01001225 * This corresponds to table 10.15 of the FF-A v1.1 EAC0 specification, "Memory
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001226 * access permissions descriptor".
1227 */
1228struct ffa_memory_region_attributes {
1229 /** The ID of the VM to which the memory is being given or shared. */
J-Alves19e20cf2023-08-02 12:48:55 +01001230 ffa_id_t receiver;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001231 /**
1232 * The permissions with which the memory region should be mapped in the
1233 * receiver's page table.
1234 */
1235 ffa_memory_access_permissions_t permissions;
1236 /**
1237 * Flags used during FFA_MEM_RETRIEVE_REQ and FFA_MEM_RETRIEVE_RESP
1238 * for memory regions with multiple borrowers.
1239 */
1240 ffa_memory_receiver_flags_t flags;
1241};
1242
1243/** Flags to control the behaviour of a memory sharing transaction. */
1244typedef uint32_t ffa_memory_region_flags_t;
1245
1246/**
1247 * Clear memory region contents after unmapping it from the sender and before
1248 * mapping it for any receiver.
1249 */
1250#define FFA_MEMORY_REGION_FLAG_CLEAR 0x1
1251
1252/**
1253 * Whether the hypervisor may time slice the memory sharing or retrieval
1254 * operation.
1255 */
1256#define FFA_MEMORY_REGION_FLAG_TIME_SLICE 0x2
1257
1258/**
1259 * Whether the hypervisor should clear the memory region after the receiver
1260 * relinquishes it or is aborted.
1261 */
1262#define FFA_MEMORY_REGION_FLAG_CLEAR_RELINQUISH 0x4
1263
J-Alves3456e032023-07-20 12:20:05 +01001264/**
1265 * On retrieve request, bypass the multi-borrower check.
1266 */
1267#define FFA_MEMORY_REGION_FLAG_BYPASS_BORROWERS_CHECK (0x1U << 10)
1268
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001269#define FFA_MEMORY_REGION_TRANSACTION_TYPE_MASK ((0x3U) << 3)
1270#define FFA_MEMORY_REGION_TRANSACTION_TYPE_UNSPECIFIED ((0x0U) << 3)
1271#define FFA_MEMORY_REGION_TRANSACTION_TYPE_SHARE ((0x1U) << 3)
1272#define FFA_MEMORY_REGION_TRANSACTION_TYPE_LEND ((0x2U) << 3)
1273#define FFA_MEMORY_REGION_TRANSACTION_TYPE_DONATE ((0x3U) << 3)
1274
Federico Recanati85090c42021-12-15 13:17:54 +01001275#define FFA_MEMORY_REGION_ADDRESS_RANGE_HINT_VALID ((0x1U) << 9)
1276#define FFA_MEMORY_REGION_ADDRESS_RANGE_HINT_MASK ((0xFU) << 5)
1277
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001278/**
Daniel Boulbyde974ca2023-12-12 13:53:31 +00001279 * Struct to store the impdef value seen in Table 11.16 of the
1280 * FF-A v1.2 ALP0 specification "Endpoint memory access descriptor".
1281 */
1282struct ffa_memory_access_impdef {
1283 uint64_t val[2];
1284};
1285
Daniel Boulbye0ca9a02024-03-05 18:40:59 +00001286static inline struct ffa_memory_access_impdef ffa_memory_access_impdef_init(
1287 uint64_t impdef_hi, uint64_t impdef_lo)
1288{
1289 return (struct ffa_memory_access_impdef){{impdef_hi, impdef_lo}};
1290}
1291
Daniel Boulbyde974ca2023-12-12 13:53:31 +00001292/**
J-Alves0b6653d2022-04-22 13:17:38 +01001293 * This corresponds to table 10.16 of the FF-A v1.1 EAC0 specification,
1294 * "Endpoint memory access descriptor".
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001295 */
1296struct ffa_memory_access {
1297 struct ffa_memory_region_attributes receiver_permissions;
1298 /**
1299 * Offset in bytes from the start of the outer `ffa_memory_region` to
1300 * an `ffa_composite_memory_region` struct.
1301 */
1302 uint32_t composite_memory_region_offset;
Daniel Boulbyde974ca2023-12-12 13:53:31 +00001303 struct ffa_memory_access_impdef impdef;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001304 uint64_t reserved_0;
1305};
1306
J-Alves363f5722022-04-25 17:37:37 +01001307/** The maximum number of recipients a memory region may be sent to. */
J-Alvesba0e6172022-04-25 17:41:40 +01001308#define MAX_MEM_SHARE_RECIPIENTS UINT32_C(2)
J-Alves363f5722022-04-25 17:37:37 +01001309
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001310/**
1311 * Information about a set of pages which are being shared. This corresponds to
J-Alves0b6653d2022-04-22 13:17:38 +01001312 * table 10.20 of the FF-A v1.1 EAC0 specification, "Lend, donate or share
1313 * memory transaction descriptor". Note that it is also used for retrieve
1314 * requests and responses.
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001315 */
1316struct ffa_memory_region {
1317 /**
1318 * The ID of the VM which originally sent the memory region, i.e. the
1319 * owner.
1320 */
J-Alves19e20cf2023-08-02 12:48:55 +01001321 ffa_id_t sender;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001322 ffa_memory_attributes_t attributes;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001323 /** Flags to control behaviour of the transaction. */
1324 ffa_memory_region_flags_t flags;
1325 ffa_memory_handle_t handle;
1326 /**
1327 * An implementation defined value associated with the receiver and the
1328 * memory region.
1329 */
1330 uint64_t tag;
J-Alves0b6653d2022-04-22 13:17:38 +01001331 /* Size of the memory access descriptor. */
1332 uint32_t memory_access_desc_size;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001333 /**
1334 * The number of `ffa_memory_access` entries included in this
1335 * transaction.
1336 */
1337 uint32_t receiver_count;
1338 /**
J-Alves0b6653d2022-04-22 13:17:38 +01001339 * Offset of the 'receivers' field, which relates to the memory access
1340 * descriptors.
1341 */
1342 uint32_t receivers_offset;
1343 /** Reserved field (12 bytes) must be 0. */
1344 uint32_t reserved[3];
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001345};
1346
1347/**
1348 * Descriptor used for FFA_MEM_RELINQUISH requests. This corresponds to table
J-Alves0b6653d2022-04-22 13:17:38 +01001349 * 16.25 of the FF-A v1.1 EAC0 specification, "Descriptor to relinquish a memory
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001350 * region".
1351 */
1352struct ffa_mem_relinquish {
1353 ffa_memory_handle_t handle;
1354 ffa_memory_region_flags_t flags;
1355 uint32_t endpoint_count;
J-Alves19e20cf2023-08-02 12:48:55 +01001356 ffa_id_t endpoints[];
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001357};
1358
1359/**
Daniel Boulby59ffee92023-11-02 18:26:26 +00001360 * Returns the first FF-A version that matches the memory access descriptor
1361 * size.
Daniel Boulbyde974ca2023-12-12 13:53:31 +00001362 */
Karl Meakin0e617d92024-04-05 12:55:22 +01001363enum ffa_version ffa_version_from_memory_access_desc_size(
Daniel Boulbyc7dc9322023-10-27 15:12:07 +01001364 uint32_t memory_access_desc_size);
1365
1366/**
Daniel Boulbyd5ae44b2023-12-12 12:18:11 +00001367 * To maintain forwards compatability we can't make assumptions about the size
1368 * of the endpoint memory access descriptor so provide a helper function
1369 * to get a receiver from the receiver array using the memory access descriptor
1370 * size field from the memory region descriptor struct.
1371 * Returns NULL if we cannot return the receiver.
1372 */
1373static inline struct ffa_memory_access *ffa_memory_region_get_receiver(
1374 struct ffa_memory_region *memory_region, uint32_t receiver_index)
1375{
1376 uint32_t memory_access_desc_size =
1377 memory_region->memory_access_desc_size;
1378
1379 if (receiver_index >= memory_region->receiver_count) {
1380 return NULL;
1381 }
1382
1383 /*
1384 * Memory access descriptor size cannot be greater than the size of
1385 * the memory access descriptor defined by the current FF-A version.
1386 */
1387 if (memory_access_desc_size > sizeof(struct ffa_memory_access)) {
1388 return NULL;
1389 }
1390
Daniel Boulby41ef8ba2023-10-13 17:01:22 +01001391 /* Check we cannot use receivers offset to cause overflow. */
1392 if (memory_region->receivers_offset !=
1393 sizeof(struct ffa_memory_region)) {
1394 return NULL;
1395 }
1396
Karl Meakin2ad6b662024-07-29 20:45:40 +01001397 return (struct ffa_memory_access
1398 *)((uint8_t *)memory_region +
1399 (size_t)memory_region->receivers_offset +
1400 (size_t)(receiver_index * memory_access_desc_size));
Daniel Boulbyd5ae44b2023-12-12 12:18:11 +00001401}
1402
1403/**
Daniel Boulby59ffee92023-11-02 18:26:26 +00001404 * Gets the receiver's access permissions from 'struct ffa_memory_region' and
1405 * returns its index in the receiver's array. If receiver's ID doesn't exist
1406 * in the array, return the region's 'receivers_count'.
1407 */
1408static inline uint32_t ffa_memory_region_get_receiver_index(
1409 struct ffa_memory_region *memory_region, ffa_id_t receiver_id)
1410{
1411 uint32_t i;
1412
1413 for (i = 0U; i < memory_region->receiver_count; i++) {
1414 struct ffa_memory_access *receiver =
1415 ffa_memory_region_get_receiver(memory_region, i);
1416 if (receiver->receiver_permissions.receiver == receiver_id) {
1417 break;
1418 }
1419 }
1420
1421 return i;
1422}
1423
1424/**
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001425 * Gets the `ffa_composite_memory_region` for the given receiver from an
1426 * `ffa_memory_region`, or NULL if it is not valid.
1427 */
1428static inline struct ffa_composite_memory_region *
1429ffa_memory_region_get_composite(struct ffa_memory_region *memory_region,
1430 uint32_t receiver_index)
1431{
Daniel Boulbyd5ae44b2023-12-12 12:18:11 +00001432 struct ffa_memory_access *receiver =
1433 ffa_memory_region_get_receiver(memory_region, receiver_index);
1434 uint32_t offset;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001435
Daniel Boulbyd5ae44b2023-12-12 12:18:11 +00001436 if (receiver == NULL) {
1437 return NULL;
1438 }
1439
1440 offset = receiver->composite_memory_region_offset;
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001441 if (offset == 0) {
1442 return NULL;
1443 }
1444
1445 return (struct ffa_composite_memory_region *)((uint8_t *)memory_region +
1446 offset);
1447}
1448
1449static inline uint32_t ffa_mem_relinquish_init(
1450 struct ffa_mem_relinquish *relinquish_request,
1451 ffa_memory_handle_t handle, ffa_memory_region_flags_t flags,
J-Alves19e20cf2023-08-02 12:48:55 +01001452 ffa_id_t sender)
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001453{
1454 relinquish_request->handle = handle;
1455 relinquish_request->flags = flags;
1456 relinquish_request->endpoint_count = 1;
1457 relinquish_request->endpoints[0] = sender;
J-Alves19e20cf2023-08-02 12:48:55 +01001458 return sizeof(struct ffa_mem_relinquish) + sizeof(ffa_id_t);
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001459}
1460
J-Alves126ab502022-09-29 11:37:33 +01001461void ffa_copy_memory_region_constituents(
1462 struct ffa_memory_region_constituent *dest,
1463 const struct ffa_memory_region_constituent *src);
1464
Karl Meakin0fd67292024-02-06 17:33:05 +00001465struct ffa_features_rxtx_map_params {
1466 /*
1467 * Bit[0:1]:
1468 * Minimum buffer size and alignment boundary:
1469 * 0b00: 4K
1470 * 0b01: 64K
1471 * 0b10: 16K
1472 * 0b11: Reserved
1473 */
1474 uint8_t min_buf_size : 2;
1475 /*
1476 * Bit[2:15]:
1477 * Reserved (MBZ)
1478 */
1479 uint16_t mbz : 14;
1480 /*
1481 * Bit[16:32]:
1482 * Maximum buffer size in number of pages
1483 * Only present on version 1.2 or later
1484 */
1485 uint16_t max_buf_size : 16;
1486};
1487
Karl Meakin49ec1e42024-05-10 13:08:24 +01001488enum ffa_features_rxtx_map_buf_size {
1489 FFA_RXTX_MAP_MIN_BUF_4K = 0,
1490 FFA_RXTX_MAP_MAX_BUF_PAGE_COUNT = 1,
1491};
Karl Meakin0fd67292024-02-06 17:33:05 +00001492
Karl Meakinf7861302024-02-20 14:39:33 +00001493static inline struct ffa_features_rxtx_map_params ffa_features_rxtx_map_params(
1494 struct ffa_value args)
1495{
1496 struct ffa_features_rxtx_map_params params;
1497 uint32_t arg2 = args.arg2;
1498
1499 params = *(struct ffa_features_rxtx_map_params *)(&arg2);
1500
1501 return params;
1502}
1503
Federico Recanati392be392022-02-08 20:53:03 +01001504/**
1505 * Endpoint RX/TX descriptor, as defined by Table 13.27 in FF-A v1.1 EAC0.
1506 * It's used by the Hypervisor to describe the RX/TX buffers mapped by a VM
1507 * to the SPMC, in order to allow indirect messaging.
1508 */
1509struct ffa_endpoint_rx_tx_descriptor {
J-Alves19e20cf2023-08-02 12:48:55 +01001510 ffa_id_t endpoint_id;
Federico Recanati392be392022-02-08 20:53:03 +01001511 uint16_t reserved;
1512
1513 /*
1514 * 8-byte aligned offset from the base address of this descriptor to the
1515 * `ffa_composite_memory_region` describing the RX buffer.
1516 */
1517 uint32_t rx_offset;
1518
1519 /*
1520 * 8-byte aligned offset from the base address of this descriptor to the
1521 * `ffa_composite_memory_region` describing the TX buffer.
1522 */
1523 uint32_t tx_offset;
1524
1525 /* Pad to align on 16-byte boundary. */
1526 uint32_t pad;
1527};
1528
1529static inline struct ffa_composite_memory_region *
Karl Meakinb9705e22024-04-05 13:58:28 +01001530ffa_endpoint_get_rx_memory_region(struct ffa_endpoint_rx_tx_descriptor *desc)
Federico Recanati392be392022-02-08 20:53:03 +01001531{
Karl Meakin2ad6b662024-07-29 20:45:40 +01001532 return (struct ffa_composite_memory_region *)((char *)desc +
Federico Recanati392be392022-02-08 20:53:03 +01001533 desc->rx_offset);
1534}
1535
1536static inline struct ffa_composite_memory_region *
Karl Meakinb9705e22024-04-05 13:58:28 +01001537ffa_endpoint_get_tx_memory_region(struct ffa_endpoint_rx_tx_descriptor *desc)
Federico Recanati392be392022-02-08 20:53:03 +01001538{
Karl Meakin2ad6b662024-07-29 20:45:40 +01001539 return (struct ffa_composite_memory_region *)((char *)desc +
Federico Recanati392be392022-02-08 20:53:03 +01001540 desc->tx_offset);
1541}
1542
J-Alves2d8457f2022-10-05 11:06:41 +01001543void ffa_memory_region_init_header(struct ffa_memory_region *memory_region,
J-Alves19e20cf2023-08-02 12:48:55 +01001544 ffa_id_t sender,
J-Alves2d8457f2022-10-05 11:06:41 +01001545 ffa_memory_attributes_t attributes,
1546 ffa_memory_region_flags_t flags,
1547 ffa_memory_handle_t handle, uint32_t tag,
Daniel Boulbyd5ae44b2023-12-12 12:18:11 +00001548 uint32_t receiver_count,
1549 uint32_t receiver_desc_size);
Daniel Boulby59ffee92023-11-02 18:26:26 +00001550void ffa_memory_access_init(struct ffa_memory_access *receiver,
1551 ffa_id_t receiver_id,
1552 enum ffa_data_access data_access,
1553 enum ffa_instruction_access instruction_access,
1554 ffa_memory_receiver_flags_t flags,
1555 struct ffa_memory_access_impdef *impdef_val);
J-Alves45085432022-04-22 16:19:20 +01001556uint32_t ffa_memory_region_init_single_receiver(
Andrew Walbranca808b12020-05-15 17:22:28 +01001557 struct ffa_memory_region *memory_region, size_t memory_region_max_size,
J-Alves19e20cf2023-08-02 12:48:55 +01001558 ffa_id_t sender, ffa_id_t receiver,
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001559 const struct ffa_memory_region_constituent constituents[],
1560 uint32_t constituent_count, uint32_t tag,
1561 ffa_memory_region_flags_t flags, enum ffa_data_access data_access,
1562 enum ffa_instruction_access instruction_access,
1563 enum ffa_memory_type type, enum ffa_memory_cacheability cacheability,
Daniel Boulby59ffee92023-11-02 18:26:26 +00001564 enum ffa_memory_shareability shareability,
1565 struct ffa_memory_access_impdef *impdef_val, uint32_t *fragment_length,
Andrew Walbranca808b12020-05-15 17:22:28 +01001566 uint32_t *total_length);
J-Alvesf4eecf72022-07-20 16:05:34 +01001567uint32_t ffa_memory_region_init(
1568 struct ffa_memory_region *memory_region, size_t memory_region_max_size,
J-Alves19e20cf2023-08-02 12:48:55 +01001569 ffa_id_t sender, struct ffa_memory_access receivers[],
Daniel Boulbyd5ae44b2023-12-12 12:18:11 +00001570 uint32_t receiver_count, uint32_t receiver_desc_size,
J-Alvesf4eecf72022-07-20 16:05:34 +01001571 const struct ffa_memory_region_constituent constituents[],
1572 uint32_t constituent_count, uint32_t tag,
1573 ffa_memory_region_flags_t flags, enum ffa_memory_type type,
1574 enum ffa_memory_cacheability cacheability,
1575 enum ffa_memory_shareability shareability, uint32_t *fragment_length,
1576 uint32_t *total_length);
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001577uint32_t ffa_memory_retrieve_request_init(
1578 struct ffa_memory_region *memory_region, ffa_memory_handle_t handle,
J-Alves19e20cf2023-08-02 12:48:55 +01001579 ffa_id_t sender, struct ffa_memory_access receivers[],
Daniel Boulbyd5ae44b2023-12-12 12:18:11 +00001580 uint32_t receiver_count, uint32_t receiver_desc_size, uint32_t tag,
1581 ffa_memory_region_flags_t flags, enum ffa_memory_type type,
1582 enum ffa_memory_cacheability cacheability,
J-Alves9b24ed82022-08-04 13:12:45 +01001583 enum ffa_memory_shareability shareability);
1584uint32_t ffa_memory_retrieve_request_init_single_receiver(
1585 struct ffa_memory_region *memory_region, ffa_memory_handle_t handle,
J-Alves19e20cf2023-08-02 12:48:55 +01001586 ffa_id_t sender, ffa_id_t receiver, uint32_t tag,
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001587 ffa_memory_region_flags_t flags, enum ffa_data_access data_access,
1588 enum ffa_instruction_access instruction_access,
1589 enum ffa_memory_type type, enum ffa_memory_cacheability cacheability,
Daniel Boulby59ffee92023-11-02 18:26:26 +00001590 enum ffa_memory_shareability shareability,
1591 struct ffa_memory_access_impdef *impdef_val);
Andrew Walbranb5ab43c2020-04-30 11:32:54 +01001592uint32_t ffa_memory_lender_retrieve_request_init(
1593 struct ffa_memory_region *memory_region, ffa_memory_handle_t handle,
J-Alves19e20cf2023-08-02 12:48:55 +01001594 ffa_id_t sender);
Andrew Walbranca808b12020-05-15 17:22:28 +01001595uint32_t ffa_memory_fragment_init(
1596 struct ffa_memory_region_constituent *fragment,
1597 size_t fragment_max_size,
1598 const struct ffa_memory_region_constituent constituents[],
1599 uint32_t constituent_count, uint32_t *fragment_length);
Federico Recanati392be392022-02-08 20:53:03 +01001600void ffa_endpoint_rx_tx_descriptor_init(
J-Alves19e20cf2023-08-02 12:48:55 +01001601 struct ffa_endpoint_rx_tx_descriptor *desc, ffa_id_t endpoint_id,
Federico Recanati392be392022-02-08 20:53:03 +01001602 uint64_t rx_address, uint64_t tx_address);