1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* 3 * Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved. 4 */ 5 6 #ifndef LIBSP_INCLUDE_FFA_API_H_ 7 #define LIBSP_INCLUDE_FFA_API_H_ 8 9 /** 10 * @file ffa_api.h 11 * @brief The file contains wrapper functions around the FF-A interfaces 12 * described in sections 7-11 of the specification. 13 */ 14 15 #include "ffa_api_types.h" 16 #include "ffa_api_defines.h" 17 #include <stdint.h> 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /** 24 * Setup and discovery interfaces 25 */ 26 27 /** 28 * @brief Queries the version of the Firmware Framework implementation at 29 * the FF-A instance. 30 * 31 * @param[out] version Version number of the FF-A implementation 32 * 33 * @return The FF-A error status code 34 */ 35 ffa_result ffa_version(uint32_t *version); 36 37 /** 38 * @brief Queries whether the FF-A interface is implemented of the 39 * component at the higher EL and if it implements any optional 40 * features. The meaning of the interface_properties structure 41 * depends on the queried FF-A function and it is described in 42 * section 8.2 of the FF-A standard (v1.0). 43 * 44 * @param[in] ffa_function_id The function id of the queried FF-A 45 * function 46 * @param[out] interface_properties Used to encode any optional features 47 * implemented or any implementation details 48 * exported by the queried interface 49 * 50 * @return The FF-A error status code 51 */ 52 ffa_result ffa_features(uint32_t ffa_function_id, 53 struct ffa_interface_properties *interface_properties); 54 55 /** 56 * @brief Relinquishes the ownership of the RX buffer after reading a 57 * message from it. 58 * 59 * @return The FF-A error status code 60 */ 61 ffa_result ffa_rx_release(void); 62 63 /** 64 * @brief Maps the RX/TX buffer pair in the callee's translation regime. 65 * 66 * @param[in] tx_buffer Base address of the TX buffer 67 * @param[in] rx_buffer Base address of the RX buffer 68 * @param[in] page_count Number of contiguous 4K pages allocated for each 69 * buffer 70 * 71 * @return The FF-A error status code 72 */ 73 ffa_result ffa_rxtx_map(const void *tx_buffer, const void *rx_buffer, 74 uint32_t page_count); 75 76 /** 77 * @brief Unmaps the RX/TX buffer pair in the callee's translation regime. 78 * 79 * @param[in] id ID of FF-A component that allocated the RX/TX buffer 80 * 81 * @return The FF-A error status code 82 */ 83 ffa_result ffa_rxtx_unmap(uint16_t id); 84 85 #if CFG_FFA_VERSION == FFA_VERSION_1_0 86 /** 87 * @brief Requests the SPM to return information about the partitions of 88 * the system. Nil UUID can be used to return information about all 89 * the SPs of the system. The information is returned in the RX 90 * buffer of the caller as an array of ffa_partition_information 91 * structures. 92 * This is an FF-A v1.0 call. 93 * 94 * @param[in] uuid The uuid 95 * @param[out] count Count of partition information descriptors populated in 96 * RX buffer of caller 97 * 98 * @return The FF-A error status code 99 */ 100 ffa_result ffa_partition_info_get(const struct ffa_uuid *uuid, uint32_t *count); 101 #elif CFG_FFA_VERSION >= FFA_VERSION_1_1 102 103 /** 104 * @brief Requests the SPM to return information about the partitions of 105 * the system. Nil UUID can be used to return information about all 106 * the SPs of the system. The information is returned in the RX 107 * buffer of the caller as an array of ffa_partition_information 108 * structures. 109 * By settings the flags parameter, the function can be instructed 110 * to only return the count of SPs with the matching UUID. 111 * This is an FF-A v1.1 call. 112 * 113 * @param[in] uuid The uuid 114 * @param[in] flags FFA_PARTITION_INFO_GET_FLAG_* flag value 115 * @param[out] count Count of matching SPs 116 * @param[out] size Size of the partition information descriptors 117 * @return ffa_result 118 */ 119 ffa_result ffa_partition_info_get(const struct ffa_uuid *uuid, uint32_t flags, 120 uint32_t *count, uint32_t *size); 121 #endif /* CFG_FFA_VERSION */ 122 123 /** 124 * @brief Returns the 16 bit ID of the calling FF-A component 125 * 126 * @param id ID of the caller 127 * 128 * @return The FF-A error status code 129 */ 130 ffa_result ffa_id_get(uint16_t *id); 131 132 /** 133 * CPU cycle management interfaces 134 */ 135 136 /** 137 * @brief Blocks the caller until a message is available or until an 138 * interrupt happens. It is also used to indicate the completion of 139 * the boot phase and the end of the interrupt handling. 140 * @note The ffa_interrupt_handler function can be called during the 141 * execution of this function. 142 * 143 * @param[out] msg The incoming message 144 * 145 * @return The FF-A error status code 146 */ 147 ffa_result ffa_msg_wait(struct ffa_direct_msg *msg); 148 149 /** Messaging interfaces */ 150 151 /** 152 * @brief Sends a 32 bit partition message in parameter registers as a 153 * request and blocks until the response is available. 154 * @note The ffa_interrupt_handler function can be called during the 155 * execution of this function 156 * 157 * @param[in] source Source endpoint ID 158 * @param[in] dest Destination endpoint ID 159 * @param[in] a0,a1,a2,a3,a4 Implementation defined message values 160 * @param[out] msg The response message 161 * 162 * @return The FF-A error status code 163 */ 164 ffa_result ffa_msg_send_direct_req_32(uint16_t source, uint16_t dest, 165 uint32_t a0, uint32_t a1, uint32_t a2, 166 uint32_t a3, uint32_t a4, 167 struct ffa_direct_msg *msg); 168 169 /** 170 * @brief Sends a 64 bit partition message in parameter registers as a 171 * request and blocks until the response is available. 172 * @note The ffa_interrupt_handler function can be called during the 173 * execution of this function 174 * 175 * @param[in] source Source endpoint ID 176 * @param[in] dest Destination endpoint ID 177 * @param[in] a0,a1,a2,a3,a4 Implementation defined message values 178 * @param[out] msg The response message 179 * 180 * @return The FF-A error status code 181 */ 182 ffa_result ffa_msg_send_direct_req_64(uint16_t source, uint16_t dest, 183 uint64_t a0, uint64_t a1, uint64_t a2, 184 uint64_t a3, uint64_t a4, 185 struct ffa_direct_msg *msg); 186 187 /** 188 * @brief Sends a 32 bit partition message in parameter registers as a 189 * response and blocks until the response is available. 190 * @note The ffa_interrupt_handler function can be called during the 191 * execution of this function 192 * 193 * @param[in] source Source endpoint ID 194 * @param[in] dest Destination endpoint ID 195 * @param[in] a0,a1,a2,a3,a4 Implementation defined message values 196 * @param[out] msg The response message 197 * 198 * @return The FF-A error status code 199 */ 200 ffa_result ffa_msg_send_direct_resp_32(uint16_t source, uint16_t dest, 201 uint32_t a0, uint32_t a1, uint32_t a2, 202 uint32_t a3, uint32_t a4, 203 struct ffa_direct_msg *msg); 204 205 /** 206 * @brief Sends a 64 bit partition message in parameter registers as a 207 * response and blocks until the response is available. 208 * @note The ffa_interrupt_handler function can be called during the 209 * execution of this function 210 * 211 * @param[in] source Source endpoint ID 212 * @param[in] dest Destination endpoint ID 213 * @param[in] a0,a1,a2,a3,a4 Implementation defined message values 214 * @param[out] msg The response message 215 * 216 * @return The FF-A error status code 217 */ 218 ffa_result ffa_msg_send_direct_resp_64(uint16_t source, uint16_t dest, 219 uint64_t a0, uint64_t a1, uint64_t a2, 220 uint64_t a3, uint64_t a4, 221 struct ffa_direct_msg *msg); 222 223 /** 224 * Memory management interfaces 225 * 226 * @note Functions with _rxtx suffix use the RX/TX buffers mapped by 227 * ffa_rxtx_map to transmit memory descriptors instead of an distinct buffer 228 * allocated by the owner. 229 */ 230 231 /** 232 * @brief Starts a transaction to transfer of ownership of a memory region 233 * from a Sender endpoint to a Receiver endpoint. 234 * 235 * @param[in] total_length Total length of the memory transaction 236 * descriptor in bytes 237 * @param[in] fragment_length Length in bytes of the memory transaction 238 * descriptor passed in this ABI invocation 239 * @param[in] buffer_address Base address of a buffer allocated by the Owner 240 * and distinct from the TX buffer 241 * @param[in] page_count Number of 4K pages in the buffer allocated by 242 * the Owner and distinct from the TX buffer 243 * @param[out] handle Globally unique Handle to identify the memory 244 * region upon successful transmission of the 245 * transaction descriptor. 246 * 247 * @return The FF-A error status code 248 */ 249 ffa_result ffa_mem_donate(uint32_t total_length, uint32_t fragment_length, 250 void *buffer_address, uint32_t page_count, 251 uint64_t *handle); 252 253 ffa_result ffa_mem_donate_rxtx(uint32_t total_length, uint32_t fragment_length, 254 uint64_t *handle); 255 256 /** 257 * @brief Starts a transaction to transfer an Owner’s access to a memory 258 * region and grant access to it to one or more Borrowers. 259 * 260 * @param[in] total_length Total length of the memory transaction 261 * descriptor in bytes 262 * @param[in] fragment_length Length in bytes of the memory transaction 263 * descriptor passed in this ABI invocation 264 * @param[in] buffer_address Base address of a buffer allocated by the Owner 265 * and distinct from the TX buffer 266 * @param[in] page_count Number of 4K pages in the buffer allocated by 267 * the Owner and distinct from the TX buffer 268 * @param[out] handle Globally unique Handle to identify the memory 269 * region upon successful transmission of the 270 * transaction descriptor. 271 * 272 * @return The FF-A error status code 273 */ 274 ffa_result ffa_mem_lend(uint32_t total_length, uint32_t fragment_length, 275 void *buffer_address, uint32_t page_count, 276 uint64_t *handle); 277 278 ffa_result ffa_mem_lend_rxtx(uint32_t total_length, uint32_t fragment_length, 279 uint64_t *handle); 280 281 /** 282 * @brief Starts a transaction to grant access to a memory region to one or 283 * more Borrowers. 284 * 285 * @param[in] total_length Total length of the memory transaction 286 * descriptor in bytes 287 * @param[in] fragment_length Length in bytes of the memory transaction 288 * descriptor passed in this ABI invocation 289 * @param[in] buffer_address Base address of a buffer allocated by the Owner 290 * and distinct from the TX buffer 291 * @param[in] page_count Number of 4K pages in the buffer allocated by 292 * the Owner and distinct from the TX buffer 293 * @param[out] handle Globally unique Handle to identify the memory 294 * region upon successful transmission of the 295 * transaction descriptor. 296 * 297 * @return The FF-A error status code 298 */ 299 ffa_result ffa_mem_share(uint32_t total_length, uint32_t fragment_length, 300 void *buffer_address, uint32_t page_count, 301 uint64_t *handle); 302 303 ffa_result ffa_mem_share_rxtx(uint32_t total_length, uint32_t fragment_length, 304 uint64_t *handle); 305 306 /** 307 * @brief Requests completion of a donate, lend or share memory management 308 * transaction. 309 * 310 * @param[in] total_length Total length of the memory transaction 311 * descriptor in bytes 312 * @param[in] fragment_length Length in bytes of the memory transaction 313 * descriptor passed in this ABI invocation 314 * @param[in] buffer_address Base address of a buffer allocated by the 315 * Owner and distinct from the TX buffer 316 * @param[in] page_count Number of 4K pages in the buffer allocated 317 * by the Owner and distinct from the TX 318 * buffer 319 * @param[out] resp_total_length Total length of the response memory 320 * transaction descriptor in bytes 321 * @param[out] resp_fragment_length Length in bytes of the response memory 322 * transaction descriptor passed in this ABI 323 * invocation 324 * 325 * @return The FF-A error status code 326 */ 327 ffa_result ffa_mem_retrieve_req(uint32_t total_length, uint32_t fragment_length, 328 void *buffer_address, uint32_t page_count, 329 uint32_t *resp_total_length, 330 uint32_t *resp_fragment_length); 331 332 ffa_result ffa_mem_retrieve_req_rxtx(uint32_t total_length, 333 uint32_t fragment_length, 334 uint32_t *resp_total_length, 335 uint32_t *resp_fragment_length); 336 337 /** 338 * @brief Starts a transaction to transfer access to a shared or lent 339 * memory region from a Borrower back to its Owner. 340 * 341 * @return The FF-A error status code 342 */ 343 ffa_result ffa_mem_relinquish(void); 344 345 /** 346 * @brief Restores exclusive access to a memory region back to its Owner. 347 * 348 * @param[in] handle Globally unique Handle to identify the memory region 349 * @param[in] flags Flags for modifying the reclaim behavior 350 * 351 * @return The FF-A error status code 352 */ 353 ffa_result ffa_mem_reclaim(uint64_t handle, uint32_t flags); 354 355 /** 356 * @brief Queries the memory attributes of a memory region. This function 357 * can only access the regions of the SP's own translation regine. 358 * Moreover this interface is only available in the boot phase, 359 * i.e. before invoking FFA_MSG_WAIT interface. 360 * 361 * @param[in] base_address Base VA of a translation granule whose 362 * permission attributes must be returned. 363 * @param[out] mem_perm Permission attributes of the memory region 364 * 365 * @return The FF-A error status code 366 */ 367 ffa_result ffa_mem_perm_get(const void *base_address, uint32_t *mem_perm); 368 369 /** 370 * @brief Sets the memory attributes of a memory regions. This function 371 * can only access the regions of the SP's own translation regine. 372 * Moreover this interface is only available in the boot phase, 373 * i.e. before invoking FFA_MSG_WAIT interface. 374 * 375 * @param[in] base_address Base VA of a memory region whose permission 376 * attributes must be set. 377 * @param[in] page_count Number of translation granule size pages 378 * starting from the Base address whose permissions 379 * must be set. 380 * @param[in] mem_perm Permission attributes to be set for the memory 381 * region 382 * @return The FF-A error status code 383 */ 384 ffa_result ffa_mem_perm_set(const void *base_address, uint32_t page_count, 385 uint32_t mem_perm); 386 387 /** 388 * @brief Allow an entity to provide debug logging to the console. Uses 389 * 32 bit registers to pass characters. 390 * 391 * @param message Message characters 392 * @param length Message length, max FFA_CONSOLE_LOG_32_MAX_LENGTH 393 * @return The FF-A error status code 394 */ 395 ffa_result ffa_console_log_32(const char *message, size_t length); 396 397 /** 398 * @brief Allow an entity to provide debug logging to the console. Uses 399 * 64 bit registers to pass characters. 400 * 401 * @param message Message characters 402 * @param length Message length, max FFA_CONSOLE_LOG_64_MAX_LENGTH 403 * @return The FF-A error status code 404 */ 405 ffa_result ffa_console_log_64(const char *message, size_t length); 406 407 /** 408 * @brief Interrupt handler prototype. Must be implemented by another 409 * component. 410 * 411 * @param[in] interrupt_id The interrupt identifier 412 */ 413 void ffa_interrupt_handler(uint32_t interrupt_id); 414 415 /** 416 * @brief VM created message handler prototype. Must be implemented by 417 * another component. 418 * 419 * @param[in] vm_id ID of VM that has been created 420 * @param[in] handle Globally unique Handle to identify a memory region that 421 * contains information associated with the created VM 422 * @return The FF-A error status code 423 */ 424 ffa_result ffa_vm_created_handler(uint16_t vm_id, uint64_t handle); 425 426 /** 427 * @brief VM destroyed message handler prototype. Must be implemented by 428 * another component. 429 * 430 * @param[in] vm_id ID of VM that has been destroyed 431 * @param[in] handle Globally unique Handle to identify a memory region that 432 * contains information associated with the destroyed VM 433 * @return The FF-A error status code 434 */ 435 ffa_result ffa_vm_destroyed_handler(uint16_t vm_id, uint64_t handle); 436 437 #ifdef __cplusplus 438 } 439 #endif 440 441 #endif /* LIBSP_INCLUDE_FFA_API_H_ */ 442