1 /*
2  * This library is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU Lesser General Public
4  * License as published by the Free Software Foundation;
5  * version 2.1 of the License.
6  *
7  * This library is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
10  * Lesser General Public License for more details.
11  *
12  * You should have received a copy of the GNU Lesser General Public
13  * License along with this library; If not, see <http://www.gnu.org/licenses/>.
14  */
15 #ifndef XENFOREIGNMEMORY_H
16 #define XENFOREIGNMEMORY_H
17 
18 /*
19  * This library allows you to map foreign domain memory, subject to
20  * permissions for both the process and the domain in which the
21  * process runs.
22  */
23 
24 #include <stdint.h>
25 #include <stddef.h>
26 
27 #include <xen/xen.h>
28 
29 /* Callers who don't care don't need to #include <xentoollog.h> */
30 struct xentoollog_logger;
31 
32 typedef struct xenforeignmemory_handle xenforeignmemory_handle;
33 
34 /*
35  * Return a handle onto the foreign memory mapping driver.  Logs errors.
36  *
37  * Note: After fork(2) a child process must not use any opened
38  * foreignmemory handle inherited from their parent, nor access any
39  * grant mapped areas associated with that handle.
40  *
41  * The child must open a new handle if they want to interact with
42  * foreignmemory.
43  *
44  * Calling exec(2) in a child will safely (and reliably) reclaim any
45  * resources which were allocated via a xenforeignmemory_handle in the
46  * parent.
47  *
48  * A child which does not call exec(2) may safely call
49  * xenforeignmemory_close() on a xenforeignmemory_handle inherited
50  * from their parent. This will attempt to reclaim any resources
51  * associated with that handle. Note that in some implementations this
52  * reclamation may not be completely effective, in this case any
53  * affected resources remain allocated.
54  *
55  * Calling xenforeignmemory_close() is the only safe operation on a
56  * xenforeignmemory_handle which has been inherited.
57  */
58 xenforeignmemory_handle *xenforeignmemory_open(struct xentoollog_logger *logger,
59                                                unsigned open_flags);
60 
61 /*
62  * Close a handle previously allocated with xenforeignmemory_open().
63  *
64  * Under normal circumstances (i.e. not in the child after a fork)
65  * xenforeignmemory_unmap() should be used on all mappings allocated
66  * by xenforeignmemory_map() prior to closing the handle in order to
67  * free up resources associated with those mappings.
68  *
69  * This is the only function which may be safely called on a
70  * xenforeignmemory_handle in a child after a
71  * fork. xenforeignmemory_unmap() must not be called under such
72  * circumstances.
73  */
74 int xenforeignmemory_close(xenforeignmemory_handle *fmem);
75 
76 /*
77  * Maps a range within one domain to a local address range.  Mappings
78  * must be unmapped with xenforeignmemory_unmap and should follow the
79  * same rules as mmap regarding page alignment.
80  *
81  * prot is as for mmap(2).
82  *
83  * @arr is an array of @pages gfns to be mapped linearly in the local
84  * address range. @err is an (optional) output array used to report
85  * per-page errors, as errno values.
86  *
87  * If @err is given (is non-NULL) then the mapping may partially
88  * succeed and return a valid pointer while also using @err to
89  * indicate the success (0) or failure (errno value) of the individual
90  * pages. The global errno thread local variable is not valid in this
91  * case.
92  *
93  * If @err is not given (is NULL) then on failure to map any page any
94  * successful mappings will be undone and NULL will be returned. errno
95  * will be set to correspond to the first failure (which may not be
96  * the most critical).
97  *
98  * It is also possible to return NULL due to a complete failure,
99  * i.e. failure to even attempt the mapping, in this case the global
100  * errno will have been set and the contents of @err (if given) is
101  * invalid.
102  *
103  * Note that it is also possible to return non-NULL with the contents
104  * of @err indicating failure to map every page.
105  */
106 void *xenforeignmemory_map(xenforeignmemory_handle *fmem, uint32_t dom,
107                            int prot, size_t pages,
108                            const xen_pfn_t arr[/*pages*/], int err[/*pages*/]);
109 
110 /*
111  * Almost like the previous one but also accepts two additional parameters:
112  *
113  * @addr is used as a hint address for foreign map placement (see mmap(2)).
114  * @flags is a set of additional flags as for mmap(2). Not all of the flag
115  * combinations are possible due to implementation details on different
116  * platforms.
117  */
118 void *xenforeignmemory_map2(xenforeignmemory_handle *fmem, uint32_t dom,
119                             void *addr, int prot, int flags, size_t pages,
120                             const xen_pfn_t arr[/*pages*/], int err[/*pages*/]);
121 
122 /*
123  * Unmap a mapping previous created with xenforeignmemory_map().
124  *
125  * Returns 0 on success on failure sets errno and returns -1.
126  */
127 int xenforeignmemory_unmap(xenforeignmemory_handle *fmem,
128                            void *addr, size_t pages);
129 
130 /**
131  * This function restricts the use of this handle to the specified
132  * domain.
133  *
134  * @parm fmem handle to the open foreignmemory interface
135  * @parm domid the domain id
136  * @return 0 on success, -1 on failure.
137  */
138 int xenforeignmemory_restrict(xenforeignmemory_handle *fmem,
139                               domid_t domid);
140 
141 #endif
142 
143 /*
144  * Local variables:
145  * mode: C
146  * c-file-style: "BSD"
147  * c-basic-offset: 4
148  * tab-width: 4
149  * indent-tabs-mode: nil
150  * End:
151  */
152