1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* 3 * Copyright (c) 2020, Linaro Limited 4 * Copyright (c) 2018-2026, Arm Limited. All rights reserved. 5 */ 6 7 #ifndef __FFA_H 8 #define __FFA_H 9 10 /* This is based on the FF-A 1.0 EAC specification */ 11 12 #include <smccc.h> 13 #include <stdint.h> 14 #include <util.h> 15 16 /* Error codes */ 17 #define FFA_OK 0 18 #define FFA_NOT_SUPPORTED -1 19 #define FFA_INVALID_PARAMETERS -2 20 #define FFA_NO_MEMORY -3 21 #define FFA_BUSY -4 22 #define FFA_INTERRUPTED -5 23 #define FFA_DENIED -6 24 #define FFA_RETRY -7 25 #define FFA_ABORTED -8 26 #define FFA_NO_DATA -9 27 28 /* FFA_VERSION helpers */ 29 #define FFA_VERSION_MAJOR_SHIFT U(16) 30 #define FFA_VERSION_MAJOR_MASK U(0x7FFF) 31 #define FFA_VERSION_MINOR_SHIFT U(0) 32 #define FFA_VERSION_MINOR_MASK U(0xFFFF) 33 #define MAKE_FFA_VERSION(major, minor) \ 34 ((((major) & FFA_VERSION_MAJOR_MASK) << FFA_VERSION_MAJOR_SHIFT) | \ 35 ((minor) & FFA_VERSION_MINOR_MASK)) 36 #define FFA_GET_MAJOR_VERSION(vers) \ 37 (((uint32_t)(vers) >> FFA_VERSION_MAJOR_SHIFT) & FFA_VERSION_MAJOR_MASK) 38 #define FFA_GET_MINOR_VERSION(vers) ((uint32_t)(vers) & \ 39 FFA_VERSION_MINOR_MASK) 40 41 #define FFA_VERSION_1_0 MAKE_FFA_VERSION(1, 0) 42 #define FFA_VERSION_1_1 MAKE_FFA_VERSION(1, 1) 43 #define FFA_VERSION_1_2 MAKE_FFA_VERSION(1, 2) 44 45 #define FFA_DST(x) ((x) & UINT16_MAX) 46 #define FFA_SRC(x) (((x) >> 16) & UINT16_MAX) 47 48 /* Function IDs */ 49 #define FFA_ERROR U(0x84000060) 50 #define FFA_SUCCESS_32 U(0x84000061) 51 #define FFA_SUCCESS_64 U(0xC4000061) 52 #define FFA_INTERRUPT U(0x84000062) 53 #define FFA_VERSION U(0x84000063) 54 #define FFA_FEATURES U(0x84000064) 55 #define FFA_RX_RELEASE U(0x84000065) 56 #define FFA_RX_ACQUIRE U(0x84000084) 57 #define FFA_RXTX_MAP_32 U(0x84000066) 58 #define FFA_RXTX_MAP_64 U(0xC4000066) 59 #define FFA_RXTX_UNMAP U(0x84000067) 60 #define FFA_PARTITION_INFO_GET U(0x84000068) 61 #define FFA_ID_GET U(0x84000069) 62 #define FFA_SPM_ID_GET U(0x84000085) 63 #define FFA_MSG_WAIT U(0x8400006B) 64 #define FFA_MSG_YIELD U(0x8400006C) 65 #define FFA_RUN U(0x8400006D) 66 #define FFA_MSG_SEND2 U(0x84000086) 67 #define FFA_MSG_SEND U(0x8400006E) 68 #define FFA_MSG_SEND_DIRECT_REQ_32 U(0x8400006F) 69 #define FFA_MSG_SEND_DIRECT_REQ_64 U(0xC400006F) 70 #define FFA_MSG_SEND_DIRECT_RESP_32 U(0x84000070) 71 #define FFA_MSG_SEND_DIRECT_RESP_64 U(0xC4000070) 72 #define FFA_MSG_SEND_DIRECT_REQ2 U(0xC400008D) 73 #define FFA_MSG_SEND_DIRECT_RESP2 U(0xC400008E) 74 #define FFA_MSG_POLL U(0x8400006A) 75 #define FFA_MEM_DONATE_32 U(0x84000071) 76 #define FFA_MEM_DONATE_64 U(0xC4000071) 77 #define FFA_MEM_LEND_32 U(0x84000072) 78 #define FFA_MEM_LEND_64 U(0xC4000072) 79 #define FFA_MEM_SHARE_32 U(0x84000073) 80 #define FFA_MEM_SHARE_64 U(0xC4000073) 81 #define FFA_MEM_RETRIEVE_REQ_32 U(0x84000074) 82 #define FFA_MEM_RETRIEVE_REQ_64 U(0xC4000074) 83 #define FFA_MEM_RETRIEVE_RESP U(0x84000075) 84 #define FFA_MEM_RELINQUISH U(0x84000076) 85 #define FFA_MEM_RECLAIM U(0x84000077) 86 #define FFA_MEM_FRAG_RX U(0x8400007A) 87 #define FFA_MEM_FRAG_TX U(0x8400007B) 88 #define FFA_NORMAL_WORLD_RESUME U(0x8400007C) 89 #define FFA_NOTIFICATION_BITMAP_CREATE U(0x8400007D) 90 #define FFA_NOTIFICATION_BITMAP_DESTROY U(0x8400007E) 91 #define FFA_NOTIFICATION_BIND U(0x8400007F) 92 #define FFA_NOTIFICATION_UNBIND U(0x84000080) 93 #define FFA_NOTIFICATION_SET U(0x84000081) 94 #define FFA_NOTIFICATION_GET U(0x84000082) 95 #define FFA_NOTIFICATION_INFO_GET_32 U(0x84000083) 96 #define FFA_NOTIFICATION_INFO_GET_64 U(0xC4000083) 97 #define FFA_SECONDARY_EP_REGISTER_64 U(0xC4000087) 98 #define FFA_MEM_PERM_GET_32 U(0x84000088) 99 #define FFA_MEM_PERM_GET_64 U(0xC4000088) 100 #define FFA_MEM_PERM_SET_32 U(0x84000089) 101 #define FFA_MEM_PERM_SET_64 U(0xC4000089) 102 #define FFA_CONSOLE_LOG_32 U(0x8400008A) 103 #define FFA_CONSOLE_LOG_64 U(0xC400008A) 104 #define FFA_EL3_INTR_HANDLE U(0x8400008C) 105 #define FFA_PARTITION_INFO_GET_REGS U(0xC400008B) 106 107 #define FFA_FEATURES_FUNC_ID_MASK BIT32(31) 108 #define FFA_FEATURES_FEATURE_ID_MASK GENMASK_32(7, 0) 109 110 /* Flags used in calls to FFA_NOTIFICATION_GET interface */ 111 #define FFA_NOTIF_FLAG_BITMAP_SP BIT(0) 112 #define FFA_NOTIF_FLAG_BITMAP_VM BIT(1) 113 #define FFA_NOTIF_FLAG_BITMAP_SPM BIT(2) 114 #define FFA_NOTIF_FLAG_BITMAP_HYP BIT(3) 115 116 /* Flags used in calls to FFA_NOTIFICATION_INFO_GET interface */ 117 #define FFA_NOTIF_INFO_GET_MORE_FLAG BIT(0) 118 #define FFA_NOTIF_INFO_GET_ID_LIST_SHIFT 12 119 #define FFA_NOTIF_INFO_GET_ID_COUNT_SHIFT 7 120 #define FFA_NOTIF_INFO_GET_ID_COUNT_MASK 0x1F 121 122 /* Feature IDs used with FFA_FEATURES */ 123 #define FFA_FEATURE_NOTIF_PEND_INTR U(0x1) 124 #define FFA_FEATURE_SCHEDULE_RECV_INTR U(0x2) 125 #define FFA_FEATURE_MANAGED_EXIT_INTR U(0x3) 126 127 /* Special value for traffic targeted to the Hypervisor or SPM */ 128 #define FFA_TARGET_INFO_MBZ U(0x0) 129 130 #define FFA_MSG_FLAG_FRAMEWORK BIT(31) 131 #define FFA_MSG_TYPE_MASK GENMASK_32(7, 0) 132 #define FFA_MSG_PSCI U(0x0) 133 #define FFA_MSG_SEND_VM_CREATED U(0x4) 134 #define FFA_MSG_RESP_VM_CREATED U(0x5) 135 #define FFA_MSG_SEND_VM_DESTROYED U(0x6) 136 #define FFA_MSG_RESP_VM_DESTROYED U(0x7) 137 #define FFA_MSG_VERSION_REQ U(0x8) 138 #define FFA_MSG_VERSION_RESP U(0x9) 139 140 /* 141 * Flag used as parameter to FFA_PARTITION_INFO_GET to return partition 142 * count only. 143 */ 144 #define FFA_PARTITION_INFO_GET_COUNT_FLAG BIT(0) 145 146 /* Memory attributes: Normal memory, Write-Back cacheable, Inner shareable */ 147 #define FFA_NORMAL_MEM_REG_ATTR U(0x2f) 148 149 /* Memory access permissions: Read-write */ 150 #define FFA_MEM_ACC_RW BIT(1) 151 152 /* Memory access permissions: executable */ 153 #define FFA_MEM_ACC_EXE BIT(3) 154 155 /* Memory access permissions mask */ 156 #define FFA_MEM_ACC_MASK 0xf 157 158 /* Clear memory before mapping in receiver */ 159 #define FFA_MEMORY_REGION_FLAG_CLEAR BIT(0) 160 /* Relayer may time slice this operation */ 161 #define FFA_MEMORY_REGION_FLAG_TIME_SLICE BIT(1) 162 /* Clear memory after receiver relinquishes it */ 163 #define FFA_MEMORY_REGION_FLAG_CLEAR_RELINQUISH BIT(2) 164 165 /* Share memory transaction */ 166 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_SHARE SHIFT_U32(1, 3) 167 /* Lend memory transaction */ 168 #define FFA_MEMORY_REGION_TRANSACTION_TYPE_LEND SHIFT_U32(2, 3) 169 /* Relayer must choose the alignment boundary */ 170 #define FFA_MEMORY_REGION_FLAG_ANY_ALIGNMENT 0 171 172 #define FFA_MEM_PERM_DATA_PERM GENMASK_32(1, 0) 173 #define FFA_MEM_PERM_RW U(0x1) 174 #define FFA_MEM_PERM_RO U(0x3) 175 176 #define FFA_MEM_PERM_INSTRUCTION_PERM BIT(2) 177 #define FFA_MEM_PERM_NX BIT(2) 178 #define FFA_MEM_PERM_X U(0) 179 180 #define FFA_MEM_PERM_RESERVED GENMASK_32(31, 3) 181 182 /* Special value for MBZ parameters */ 183 #define FFA_PARAM_MBZ U(0x0) 184 185 /* 186 * The W1 register in FFA_INTERRUPT and FFA_RUN interfaces contains the target 187 * information. This value has two parts, the SP ID and vCPU ID. The SP ID 188 * identifies the SP to resume and the vCPU ID identifies the vCPU or execution 189 * context to resume (FF-A v1.1 section 4.8). 190 */ 191 #define FFA_TARGET_INFO_SET(sp_id, vcpu_id) (((sp_id) << 16) | (vcpu_id)) 192 #define FFA_TARGET_INFO_GET_SP_ID(info) (((info) >> 16) & 0xffff) 193 #define FFA_TARGET_INFO_GET_VCPU_ID(info) ((info) & 0xffff) 194 195 /* 196 * Flags used for the FFA_PARTITION_INFO_GET return message: 197 * BIT(0): Supports receipt of direct requests 198 * BIT(1): Can send direct requests 199 * BIT(2): Can send and receive indirect messages 200 * BIT(3): Supports receipt of notifications 201 * BIT(4-5): Partition ID is a PE endpoint ID 202 */ 203 #define FFA_PART_PROP_DIRECT_REQ_RECV BIT(0) 204 #define FFA_PART_PROP_DIRECT_REQ_SEND BIT(1) 205 #define FFA_PART_PROP_INDIRECT_MSGS BIT(2) 206 #define FFA_PART_PROP_RECV_NOTIF BIT(3) 207 #define FFA_PART_PROP_IS_PE_ID SHIFT_U32(0, 4) 208 #define FFA_PART_PROP_IS_SEPID_INDEP SHIFT_U32(1, 4) 209 #define FFA_PART_PROP_IS_SEPID_DEP SHIFT_U32(2, 4) 210 #define FFA_PART_PROP_IS_AUX_ID SHIFT_U32(3, 4) 211 #define FFA_PART_PROP_NOTIF_CREATED BIT(6) 212 #define FFA_PART_PROP_NOTIF_DESTROYED BIT(7) 213 #define FFA_PART_PROP_AARCH64_STATE BIT(8) 214 215 #define FFA_MEMORY_HANDLE_HYPERVISOR_BIT BIT64(63) 216 #define FFA_MEMORY_HANDLE_SECURE_BIT BIT64(45) 217 #define FFA_MEMORY_HANDLE_NON_SECURE_BIT BIT64(44) 218 /* 219 * Codes the OP-TEE partition/guest ID into a cookie in order to know which 220 * partition to activate when reclaiming the shared memory. This field is 0 221 * unless CFG_NS_VIRTUALIZATION is enabled. 222 */ 223 #define FFA_MEMORY_HANDLE_PRTN_SHIFT 16 224 #define FFA_MEMORY_HANDLE_PRTN_MASK GENMASK_32(16, 0) 225 226 227 #define FFA_BOOT_INFO_NAME_LEN U(16) 228 229 /* Boot Info descriptors type */ 230 #define FFA_BOOT_INFO_TYPE_IMDEF BIT(7) 231 #define FFA_BOOT_INFO_TYPE_ID_MASK GENMASK_32(6, 0) 232 #define FFA_BOOT_INFO_TYPE_ID_FDT U(0) 233 #define FFA_BOOT_INFO_TYPE_ID_HOB U(1) 234 235 /* Boot Info descriptors flags */ 236 #define FFA_BOOT_INFO_FLAG_NAME_FORMAT_MASK GENMASK_32(1, 0) 237 #define FFA_BOOT_INFO_FLAG_NAME_FORMAT_STRING U(0) 238 #define FFA_BOOT_INFO_FLAG_NAME_FORMAT_UUID U(1) 239 240 /** Bits [3:2] encode the format of the content field in ffa_boot_info_desc. */ 241 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_SHIFT U(2) 242 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_MASK GENMASK_32(3, 2) 243 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_VALUE U(1) 244 #define FFA_BOOT_INFO_FLAG_CONTENT_FORMAT_ADDR U(0) 245 246 #define FFA_BOOT_INFO_SIGNATURE U(0xFFA) 247 #define FFA_BOOT_INFO_VERSION_1_1 U(0x10001) 248 #define FFA_BOOT_INFO_VERSION_1_2 U(0x10002) 249 250 #define FFA_CONSOLE_LOG_CHAR_COUNT_MASK GENMASK_32(7, 0) 251 #define FFA_CONSOLE_LOG_32_MAX_MSG_LEN U(24) 252 #define FFA_CONSOLE_LOG_64_V1_1_MAX_MSG_LEN U(48) 253 #define FFA_CONSOLE_LOG_64_MAX_MSG_LEN U(128) 254 255 /* Memory transaction type in FFA_MEM_RETRIEVE_RESP flags */ 256 #define FFA_MEMORY_TRANSACTION_TYPE_MASK GENMASK_32(4, 3) 257 #define FFA_MEMORY_TRANSACTION_TYPE_SHARE SHIFT_U32(1, 3) 258 #define FFA_MEMORY_TRANSACTION_TYPE_LEND SHIFT_U32(2, 3) 259 #define FFA_MEMORY_TRANSACTION_TYPE_DONATE SHIFT_U32(3, 3) 260 261 #ifndef __ASSEMBLER__ 262 /* Constituent memory region descriptor */ 263 struct ffa_address_range { 264 uint64_t address; 265 uint32_t page_count; 266 uint32_t reserved; 267 }; 268 269 /* Composite memory region descriptor */ 270 struct ffa_mem_region { 271 uint32_t total_page_count; 272 uint32_t address_range_count; 273 uint64_t reserved; 274 struct ffa_address_range address_range_array[]; 275 }; 276 277 /* Memory access permissions descriptor */ 278 struct ffa_mem_access_perm { 279 uint16_t endpoint_id; 280 uint8_t perm; 281 uint8_t flags; 282 }; 283 284 /* Endpoint memory access descriptor up to version 1.1 */ 285 struct ffa_mem_access_1_0 { 286 struct ffa_mem_access_perm access_perm; 287 uint32_t region_offs; 288 uint64_t reserved; 289 }; 290 291 /* Endpoint memory access descriptor from version 1.2 */ 292 struct ffa_mem_access_1_2 { 293 struct ffa_mem_access_perm access_perm; 294 uint32_t region_offs; 295 uint8_t impdef[16]; 296 uint64_t reserved; 297 }; 298 299 /* 300 * A common memory access descriptor where only the first two fields need 301 * to be accessed. 302 */ 303 struct ffa_mem_access_common { 304 struct ffa_mem_access_perm access_perm; 305 uint32_t region_offs; 306 }; 307 308 /* Lend, donate or share memory transaction descriptor */ 309 struct ffa_mem_transaction_1_0 { 310 uint16_t sender_id; 311 uint8_t mem_reg_attr; 312 uint8_t reserved0; 313 uint32_t flags; 314 uint64_t global_handle; 315 uint64_t tag; 316 uint32_t reserved1; 317 uint32_t mem_access_count; 318 struct ffa_mem_access_1_0 mem_access_array[]; 319 }; 320 321 struct ffa_mem_transaction_1_1 { 322 uint16_t sender_id; 323 uint16_t mem_reg_attr; 324 uint32_t flags; 325 uint64_t global_handle; 326 uint64_t tag; 327 uint32_t mem_access_size; 328 uint32_t mem_access_count; 329 uint32_t mem_access_offs; 330 uint8_t reserved[12]; 331 }; 332 333 /* 334 * The parts needed from struct ffa_mem_transaction_1_0 or struct 335 * ffa_mem_transaction_1_1, used to provide an abstraction of difference in 336 * data structures between version 1.0 and 1.1. This is just an internal 337 * interface and can be changed without changing any ABI. 338 */ 339 struct ffa_mem_transaction_x { 340 uint16_t sender_id; 341 uint8_t mem_reg_attr; 342 uint8_t flags; 343 uint8_t mem_access_size; 344 uint8_t mem_access_count; 345 uint16_t mem_access_offs; 346 uint64_t global_handle; 347 uint64_t tag; 348 }; 349 350 #define FFA_UUID_SIZE 16 351 352 /* Partition information descriptor */ 353 struct ffa_partition_info_x { 354 uint16_t id; 355 uint16_t execution_context; 356 uint32_t partition_properties; 357 /* 358 * The uuid field is absent in FF-A 1.0, and an array of 16 359 * (FFA_UUID_SIZE) from FF-A 1.1 360 */ 361 uint8_t uuid[]; 362 }; 363 364 /* Descriptor to relinquish a memory region (FFA_MEM_RELINQUISH) */ 365 struct ffa_mem_relinquish { 366 uint64_t handle; 367 uint32_t flags; 368 uint32_t endpoint_count; 369 uint16_t endpoint_id_array[]; 370 }; 371 372 /* FF-A v1.0 boot information name-value pairs */ 373 struct ffa_boot_info_nvp_1_0 { 374 uint32_t name[4]; 375 uint64_t value; 376 uint64_t size; 377 }; 378 379 /* FF-A v1.0 boot information descriptor */ 380 struct ffa_boot_info_1_0 { 381 uint32_t magic; 382 uint32_t count; 383 struct ffa_boot_info_nvp_1_0 nvp[]; 384 }; 385 386 /* FF-A v1.1 boot information descriptor */ 387 struct ffa_boot_info_1_1 { 388 char name[FFA_BOOT_INFO_NAME_LEN]; 389 uint8_t type; 390 uint8_t reserved; 391 uint16_t flags; 392 uint32_t size; 393 uint64_t contents; 394 }; 395 396 /* FF-A v1.1 boot information header */ 397 struct ffa_boot_info_header_1_1 { 398 uint32_t signature; 399 uint32_t version; 400 uint32_t blob_size; 401 uint32_t desc_size; 402 uint32_t desc_count; 403 uint32_t desc_offset; 404 uint64_t reserved; 405 }; 406 407 #endif /*__ASSEMBLER__*/ 408 #endif /* __FFA_H */ 409