1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* 3 * Copyright (c) 2020, Arm Limited and Contributors. All rights reserved. 4 */ 5 6 #ifndef LIBSP_INCLUDE_FFA_MEMORY_DESCRIPTORS_H_ 7 #define LIBSP_INCLUDE_FFA_MEMORY_DESCRIPTORS_H_ 8 9 /** 10 * @file ffa_memory_descriptor.h 11 * @brief The functions of this file were made to help building and parsing 12 * memory transaction descriptors. 13 */ 14 15 #include "ffa_api_types.h" 16 #include <stddef.h> 17 #include <stdint.h> 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /** 24 * @brief Helper buffer descriptor type for passing buffer pointer and length 25 * along the current buffer usage. 26 */ 27 struct ffa_mem_transaction_buffer { 28 void *buffer; 29 size_t length; 30 size_t used; 31 }; 32 33 /** 34 * @brief Fills the buffer descriptor to use the area specified by the 35 * address and length parameters. 36 * 37 * @param[in] address The buffer address 38 * @param[in] length The buffer length 39 * @param[out] buffer The buffer descriptor 40 */ 41 void ffa_init_mem_transaction_buffer(void *address, size_t length, 42 struct ffa_mem_transaction_buffer *buffer); 43 44 /** 45 * @brief Initializes the memory transaction descriptor (see Table 5.19) in 46 * the transaction buffer. 47 * 48 * @param[in] buffer The buffer descriptor 49 * @param[in] sender_id ID of the Owner endpoint 50 * @param[in] mem_region_attr The memory region attributes 51 * @param[in] flags The transaction flags 52 * @param[in] handle Memory region handle 53 * @param[in] tag Memory region tag 54 */ 55 void ffa_init_mem_transaction_desc(struct ffa_mem_transaction_buffer *buffer, 56 uint16_t sender_id, uint16_t mem_region_attr, 57 uint32_t flags, uint64_t handle, uint64_t tag); 58 59 /** 60 * @brief Queries the memory transaction descriptor (see Table 5.19) from 61 * the transaction buffer. 62 * 63 * @param[in] buffer The buffer descriptor 64 * 65 * @return Pointer to the transaction descriptor. 66 */ 67 const struct ffa_mem_transaction_desc * 68 ffa_get_mem_transaction_desc(struct ffa_mem_transaction_buffer *buffer); 69 70 /** 71 * @brief Reserves space for the memory access descriptors. In case of 72 * alternately adding memory access descriptors and adding memory 73 * regions to these descriptors the descriptor add will panic unless 74 * there was a sufficient amount of space reserved by this function. 75 * 76 * @param[in] buffer The buffer descriptor 77 * @param[in] count Memory access descriptor count to reserve 78 */ 79 void ffa_reserve_mem_access_desc(struct ffa_mem_transaction_buffer *buffer, 80 size_t count); 81 82 /** 83 * @brief Adds a memory access descriptor (see Table 5.16). 84 * 85 * @param[in] buffer The buffer descriptor 86 * @param[in] endpoint_id 16-bit ID of endpoint to which the memory access 87 * permissions apply 88 * @param[in] mem_access_perm Permissions used to access a memory region 89 * @param[in] flags ABI specific flags 90 * 91 * @return Index of the newly added descriptor 92 */ 93 uint32_t ffa_add_mem_access_desc(struct ffa_mem_transaction_buffer *buffer, 94 uint16_t endpoint_id, uint8_t mem_access_perm, 95 uint8_t flags); 96 97 /** 98 * @brief Queries the count of the memory access descriptors (see Table 99 * 5.16) from the transaction buffer. 100 * 101 * @param[in] buffer The buffer descriptor 102 * 103 * @return Descriptor count 104 */ 105 uint32_t 106 ffa_get_mem_access_desc_count(struct ffa_mem_transaction_buffer *buffer); 107 108 /** 109 * @brief Queries the memory access descriptor (see Table 5.16) from the 110 * transaction buffer. 111 * 112 * @param[in] buffer The buffer descriptor 113 * @param[in] descriptor_index The descriptor index 114 * 115 * @return Pointer to the memory access descriptor 116 */ 117 const struct ffa_mem_access_desc * 118 ffa_get_mem_access_desc(struct ffa_mem_transaction_buffer *buffer, 119 uint32_t descriptor_index); 120 121 /** 122 * @brief Adds a memory region to the transaction (see Table 5.13 and 5.14) 123 * 124 * @param[in] buffer The buffer descriptor 125 * @param[in] address The address of the region 126 * @param[in] page_count The size of the region in 4K pages 127 */ 128 void ffa_add_memory_region(struct ffa_mem_transaction_buffer *buffer, 129 const void *address, uint32_t page_count); 130 131 /** 132 * @brief Queries the memory region descriptor (see Table 5.13 and 5.14) 133 * from the transaction buffer. 134 * 135 * @param[in] buffer The buffer descriptor 136 * 137 * @return Pointer to the memory region descriptor 138 */ 139 const struct ffa_composite_mem_region_desc * 140 ffa_get_memory_region(struct ffa_mem_transaction_buffer *buffer); 141 142 #ifdef __cplusplus 143 } 144 #endif 145 146 #endif /* LIBSP_INCLUDE_FFA_MEMORY_DESCRIPTORS_H_ */ 147