1 /*
2  * Copyright (c) 2022, Arm Limited. All rights reserved.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining
5  * a copy of this software and associated documentation files
6  * (the "Software"), to deal in the Software without restriction,
7  * including without limitation the rights to use, copy, modify, merge,
8  * publish, distribute, sublicense, and/or sell copies of the Software,
9  * and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be
13  * included in all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22  */
23 
24 #pragma once
25 
26 #include <arch/ops.h>
27 #include <stdbool.h>
28 
29 /**
30  * arm_ffa_is_init() - Check whether this module initialized successfully.
31  *
32  * This should only be called once arm_ffa_init() is guaranteed to have
33  * returned.
34  *
35  * Return: %true in case of success, %false otherwise.
36  */
37 bool arm_ffa_is_init(void);
38 
39 /**
40  * arm_ffa_mem_relinquish() - Relinquish Trusty's access to a memory region.
41  * @handle:        Handle of object to relinquish.
42  *
43  * Relinquish shared memory object id with SPM/Hypervisor. Allows the sender to
44  * reclaim the memory (if it has not been retrieved by anyone else).
45  */
46 status_t arm_ffa_mem_relinquish(uint64_t handle);
47 
48 struct arm_ffa_cons_mrd;
49 
50 /**
51  * struct arm_ffa_mem_frag_info - A fragment of an FF-A shared memory object.
52  * @received_len: Length of the fragment.
53  * @start_index: Index of the address range array where to start reading.
54  * @count: Number of elements in the address range buffer.
55  * @address_ranges: The array of address ranges.
56  */
57 struct arm_ffa_mem_frag_info {
58     uint32_t received_len;
59     size_t start_index;
60     uint32_t count;
61     struct ffa_cons_mrd* address_ranges;
62 };
63 
64 /**
65  * arm_ffa_mem_address_range_get() - Gets one address range from the buffer.
66  * @buffer: Buffer that describes a part of an FF-A shared memory object.
67  * @index: The index of the address range to retrieve.
68  * @addr: [out] Start of the retrieved address range.
69  * @size: [out] Size of the retrieved address range.
70  *
71  * Return: 0 on success, LK error code on failure.
72  */
73 status_t arm_ffa_mem_address_range_get(struct arm_ffa_mem_frag_info* buffer,
74                                        size_t index,
75                                        paddr_t* addr,
76                                        size_t* size);
77 /**
78  * arm_ffa_mem_retrieve_start() - Retrieve a memory region from the
79  *                                SPMC/hypervisor for access from Trusty.
80  * @sender_id: Id of the memory owner.
81  * @handle: The handle identifying the memory region in the transaction.
82  * @tag: The tag identifying the transaction.
83  * @address_range_count: [out] The number of address ranges retrieved.
84  * @arch_mmu_flags: [out] The MMU flags of the received memory.
85  * @frag_info: [out] The shared memory object fragment.
86  *
87  * Only expects one descriptor in the returned memory access descriptor array,
88  * since we don't retrieve memory on behalf of anyone else.
89  *
90  * Grabs RXTX buffer lock. The lock must be subsequently released through
91  * `arm_ffa_rx_release()`.
92  *
93  * Return: 0 on success, LK error code on failure.
94  */
95 status_t arm_ffa_mem_retrieve_start(uint16_t sender_id,
96                                     uint64_t handle,
97                                     uint64_t tag,
98                                     uint32_t* address_range_count,
99                                     uint* arch_mmu_flags,
100                                     struct arm_ffa_mem_frag_info* frag_info);
101 /**
102  * arm_ffa_mem_retrieve_next_frag() - Performs an FF-A call to retrieve the
103  *                                    next fragment of a shared memory object.
104  * @handle: The handle of the FF-A memory object to retrieve.
105  * @frag_info: [out] the retrieved fragment of the memory object.
106  *
107  * Return: 0 on success, LK error code on failure.
108  */
109 status_t arm_ffa_mem_retrieve_next_frag(
110         uint64_t handle,
111         struct arm_ffa_mem_frag_info* frag_info);
112 /**
113  * arm_ffa_rx_release() - Relinquish ownership of the RX buffer.
114  *
115  * Return: 0 on success, LK error code on failure.
116  */
117 status_t arm_ffa_rx_release(void);
118