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 * Call hypercalls with varying numbers of arguments. 78 * 79 * On success the return value of the hypercall is the return value of 80 * the xencall function. On error these functions set errno and 81 * return -1. 82 * 83 * The errno values will be either: 84 * - The Xen hypercall error return (from xen/include/public/errno.h) 85 * translated into the corresponding local value for that POSIX error. 86 * - An errno value produced by the OS driver or the library 87 * implementation. Such values may be defined by POSIX or by the OS. 88 * 89 * Note that under some circumstances it will not be possible to tell 90 * whether an error came from Xen or from the OS/library. 91 * 92 * These functions never log. 93 */ 94 int xencall0(xencall_handle *xcall, unsigned int op); 95 int xencall1(xencall_handle *xcall, unsigned int op, 96 uint64_t arg1); 97 int xencall2(xencall_handle *xcall, unsigned int op, 98 uint64_t arg1, uint64_t arg2); 99 int xencall3(xencall_handle *xcall, unsigned int op, 100 uint64_t arg1, uint64_t arg2, uint64_t arg3); 101 int xencall4(xencall_handle *xcall, unsigned int op, 102 uint64_t arg1, uint64_t arg2, uint64_t arg3, 103 uint64_t arg4); 104 int xencall5(xencall_handle *xcall, unsigned int op, 105 uint64_t arg1, uint64_t arg2, uint64_t arg3, 106 uint64_t arg4, uint64_t arg5); 107 108 /* 109 * Allocate and free memory which is suitable for use as a pointer 110 * argument to a hypercall. 111 */ 112 void *xencall_alloc_buffer_pages(xencall_handle *xcall, size_t nr_pages); 113 void xencall_free_buffer_pages(xencall_handle *xcall, void *p, size_t nr_pages); 114 115 void *xencall_alloc_buffer(xencall_handle *xcall, size_t size); 116 void xencall_free_buffer(xencall_handle *xcall, void *p); 117 118 #endif 119 120 /* 121 * Local variables: 122 * mode: C 123 * c-file-style: "BSD" 124 * c-basic-offset: 4 125 * tab-width: 4 126 * indent-tabs-mode: nil 127 * End: 128 */ 129