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 typedef struct xenforeignmemory_resource_handle xenforeignmemory_resource_handle; 142 143 /** 144 * This function maps a guest resource. 145 * 146 * @parm fmem handle to the open foreignmemory interface 147 * @parm domid the domain id 148 * @parm type the resource type 149 * @parm id the type-specific resource identifier 150 * @parm frame base frame index within the resource 151 * @parm nr_frames number of frames to map 152 * @parm paddr pointer to an address passed through to mmap(2) 153 * @parm prot passed through to mmap(2) 154 * @parm POSIX-only flags passed through to mmap(2) 155 * @return pointer to foreignmemory resource handle on success, NULL on 156 * failure 157 * 158 * *paddr is used, on entry, as a hint address for foreign map placement 159 * (see mmap(2)) so should be set to NULL if no specific placement is 160 * required. On return *paddr contains the address where the resource is 161 * mapped. 162 * As for xenforeignmemory_map2() flags is a set of additional flags 163 * for mmap(2). Not all of the flag combinations are possible due to 164 * implementation details on different platforms. 165 */ 166 xenforeignmemory_resource_handle *xenforeignmemory_map_resource( 167 xenforeignmemory_handle *fmem, domid_t domid, unsigned int type, 168 unsigned int id, unsigned long frame, unsigned long nr_frames, 169 void **paddr, int prot, int flags); 170 171 /** 172 * This function releases a previously acquired resource. 173 * 174 * @parm fmem handle to the open foreignmemory interface 175 * @parm fres handle to the acquired resource 176 * 177 * Returns 0 on success on failure sets errno and returns -1. 178 */ 179 int xenforeignmemory_unmap_resource( 180 xenforeignmemory_handle *fmem, xenforeignmemory_resource_handle *fres); 181 182 #endif 183 184 /* 185 * Local variables: 186 * mode: C 187 * c-file-style: "BSD" 188 * c-basic-offset: 4 189 * tab-width: 4 190 * indent-tabs-mode: nil 191 * End: 192 */ 193