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 XENCALL_H 16 #define XENCALL_H 17 18 /* 19 * This library allows you to make arbitrary hypercalls (subject to 20 * sufficient permission for the process and the domain itself). Note 21 * that while the library interface is stable the hypercalls are 22 * subject to their own rules. 23 */ 24 25 #include <stdint.h> 26 #include <stddef.h> 27 28 /* Callers who don't care don't need to #include <xentoollog.h> */ 29 struct xentoollog_logger; 30 31 typedef struct xencall_handle xencall_handle; 32 33 /* 34 */ 35 #define XENCALL_OPENFLAG_NON_REENTRANT (1U<<0) 36 37 /* 38 * Return a handle onto the hypercall driver. Logs errors. 39 * * 40 * Note: After fork(2) a child process must not use any opened 41 * xencall handle inherited from their parent, nor access any 42 * hypercall argument buffers associated with that handle. 43 * 44 * The child must open a new handle if they want to interact with 45 * xencall. 46 * 47 * Calling exec(2) in a child will safely (and reliably) reclaim any 48 * resources which were allocated via a xencall_handle in the parent. 49 * 50 * A child which does not call exec(2) may safely call xencall_close() 51 * on a xencall_handle inherited from their parent. This will attempt 52 * to reclaim any resources associated with that handle. Note that in 53 * some implementations this reclamation may not be completely 54 * effective, in this case any affected resources remain allocated. 55 * 56 * Calling xencall_close() is the only safe operation on a 57 * xencall_handle which has been inherited. 58 */ 59 xencall_handle *xencall_open(struct xentoollog_logger *logger, 60 unsigned open_flags); 61 62 /* 63 * Close a handle previously allocated with xencall_open(). 64 * 65 * Under normal circumstances (i.e. not in the child after a fork) any 66 * allocated hypercall argument buffers should be freed using the 67 * appropriate xencall_free_*() prior to closing the handle in order 68 * to free up resources associated with those mappings. 69 * 70 * This is the only function which may be safely called on a 71 * xencall_handle in a child after a fork. xencall_free_*() must not 72 * be called under such circumstances. 73 */ 74 int xencall_close(xencall_handle *xcall); 75 76 /* 77 * Return the fd used internally by xencall. selecting on it is not 78 * useful. But it could be useful for unusual use cases; perhaps, 79 * passing to other programs, calling ioctls on directly, or maybe 80 * calling fcntl. 81 */ 82 int xencall_fd(xencall_handle *xcall); 83 84 /* 85 * Call hypercalls with varying numbers of arguments. 86 * 87 * On success the return value of the hypercall is the return value of 88 * the xencall function. On error these functions set errno and 89 * return -1. 90 * 91 * The errno values will be either: 92 * - The Xen hypercall error return (from xen/include/public/errno.h) 93 * translated into the corresponding local value for that POSIX error. 94 * - An errno value produced by the OS driver or the library 95 * implementation. Such values may be defined by POSIX or by the OS. 96 * 97 * Note that under some circumstances it will not be possible to tell 98 * whether an error came from Xen or from the OS/library. 99 * 100 * These functions never log. 101 */ 102 int xencall0(xencall_handle *xcall, unsigned int op); 103 int xencall1(xencall_handle *xcall, unsigned int op, 104 uint64_t arg1); 105 int xencall2(xencall_handle *xcall, unsigned int op, 106 uint64_t arg1, uint64_t arg2); 107 int xencall3(xencall_handle *xcall, unsigned int op, 108 uint64_t arg1, uint64_t arg2, uint64_t arg3); 109 int xencall4(xencall_handle *xcall, unsigned int op, 110 uint64_t arg1, uint64_t arg2, uint64_t arg3, 111 uint64_t arg4); 112 int xencall5(xencall_handle *xcall, unsigned int op, 113 uint64_t arg1, uint64_t arg2, uint64_t arg3, 114 uint64_t arg4, uint64_t arg5); 115 116 /* 117 * Allocate and free memory which is suitable for use as a pointer 118 * argument to a hypercall. 119 */ 120 void *xencall_alloc_buffer_pages(xencall_handle *xcall, size_t nr_pages); 121 void xencall_free_buffer_pages(xencall_handle *xcall, void *p, size_t nr_pages); 122 123 void *xencall_alloc_buffer(xencall_handle *xcall, size_t size); 124 void xencall_free_buffer(xencall_handle *xcall, void *p); 125 126 /* 127 * Are allocated hypercall buffers safe to be accessed by the hypervisor all 128 * the time? 129 * Returns 0 if EFAULT might be possible. 130 */ 131 int xencall_buffers_never_fault(xencall_handle *xcall); 132 133 #endif 134 135 /* 136 * Local variables: 137 * mode: C 138 * c-file-style: "BSD" 139 * c-basic-offset: 4 140 * tab-width: 4 141 * indent-tabs-mode: nil 142 * End: 143 */ 144