1 /*- 2 * Copyright (c) 2016 Akshay Jaggi <jaggi@FreeBSD.org> 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24 * SUCH DAMAGE. 25 * 26 * gntdev.h 27 * 28 * Interface to /dev/xen/gntdev. 29 * 30 * This device provides the user with two kinds of functionalities: 31 * 1. Grant Allocation 32 * Allocate a page of our own memory, and share it with a foreign domain. 33 * 2. Grant Mapping 34 * Map a grant allocated by a foreign domain, into our own memory. 35 * 36 * 37 * Grant Allocation 38 * 39 * Steps to allocate a grant: 40 * 1. Do an `IOCTL_GNTDEV_ALLOC_GREF ioctl`, with 41 * - `domid`, as the domain-id of the foreign domain 42 * - `flags`, ORed with GNTDEV_ALLOC_FLAG_WRITABLE if you want the foreign 43 * domain to have write access to the shared memory 44 * - `count`, with the number of pages to share with the foreign domain 45 * 46 * Ensure that the structure you allocate has enough memory to store 47 * all the allocated grant-refs, i.e., you need to allocate 48 * (sizeof(struct ioctl_gntdev_alloc_gref) + (count - 1)*sizeof(uint32_t)) 49 * bytes of memory. 50 * 51 * 2. Mmap the address given in `index` after a successful ioctl. 52 * This will give you access to the granted pages. 53 * 54 * Note: 55 * 1. The grant is not removed until all three of the following conditions 56 * are met 57 * - The region is not mmaped. That is, munmap() has been called if 58 * the region was mmapped previously. 59 * - IOCTL_GNTDEV_DEALLOC_GREF ioctl has been performed. After you 60 * perform this ioctl, you can no longer mmap or set notify on 61 * the grant. 62 * - The foreign domain has stopped using the grant. 63 * 2. Granted pages can only belong to one mmap region. 64 * 3. Every page of granted memory is a unit in itself. What this means 65 * is that you can set a unmap notification for each of the granted 66 * pages, individually; you can mmap and dealloc-ioctl a contiguous 67 * range of allocated grants (even if alloc-ioctls were performed 68 * individually), etc. 69 * 70 * 71 * Grant Mapping 72 * 73 * Steps to map a grant: 74 * 1. Do a `IOCTL_GNTDEV_MAP_GRANT_REF` ioctl, with 75 * - `count`, as the number of foreign grants to map 76 * - `refs[i].domid`, as the domain id of the foreign domain 77 * - `refs[i].ref`, as the grant-ref for the grant to be mapped 78 * 79 * 2. Mmap the address given in `index` after a successful ioctl. 80 * This will give you access to the mapped pages. 81 * 82 * Note: 83 * 1. The map hypercall is not made till the region is mmapped. 84 * 2. The unit is defined by the map ioctl. This means that only one 85 * unmap notification can be set on a group of pages that were 86 * mapped together in one ioctl, and also no single mmaping of contiguous 87 * grant-maps is possible. 88 * 3. You can mmap the same grant-map region multiple times. 89 * 4. The grant is not unmapped until both of the following conditions are met 90 * - The region is not mmaped. That is, munmap() has been called for 91 * as many times as the grant was mmapped. 92 * - IOCTL_GNTDEV_UNMAP_GRANT_REF ioctl has been called. 93 * 5. IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR ioctl gives index and count of 94 * a grant-map from the virtual address of the location where the grant 95 * is mmapped. 96 * 97 * 98 * IOCTL_GNTDEV_SET_UNMAP_NOTIFY 99 * This ioctl allows us to set notifications to be made when the grant is 100 * either unmapped (in case of a mapped grant), or when it is ready to be 101 * deallocated by us, ie, the grant is no more mmapped, and the dealloc 102 * ioctl has been called (in case of an allocated grant). OR `action` with 103 * the required notification masks, and fill in the appropriate fields. 104 * - UNMAP_NOTIFY_CLEAR_BYTE clears the byte at `index`, where index is 105 * the address of the byte in file address space. 106 * - UNMAP_NOTIFY_SEND_EVENT sends an event channel notification on 107 * `event_channel_port` 108 * In case of multiple notify ioctls, only the last one survives. 109 * 110 * $FreeBSD$ 111 */ 112 113 #ifndef __XEN_GNTDEV_H__ 114 #define __XEN_GNTDEV_H__ 115 116 #include <sys/types.h> 117 118 #define IOCTL_GNTDEV_SET_UNMAP_NOTIFY \ 119 _IOW('E', 0, struct ioctl_gntdev_unmap_notify) 120 struct ioctl_gntdev_unmap_notify { 121 /* IN parameters */ 122 uint64_t index; 123 uint32_t action; 124 uint32_t event_channel_port; 125 }; 126 127 #define UNMAP_NOTIFY_CLEAR_BYTE 0x1 128 #define UNMAP_NOTIFY_SEND_EVENT 0x2 129 130 /*-------------------- Grant Allocation IOCTLs ------------------------------*/ 131 132 #define IOCTL_GNTDEV_ALLOC_GREF \ 133 _IOWR('E', 1, struct ioctl_gntdev_alloc_gref) 134 struct ioctl_gntdev_alloc_gref { 135 /* IN parameters */ 136 uint16_t domid; 137 uint16_t flags; 138 uint32_t count; 139 /* OUT parameters */ 140 uint64_t index; 141 /* Variable OUT parameter */ 142 uint32_t *gref_ids; 143 }; 144 145 #define GNTDEV_ALLOC_FLAG_WRITABLE 1 146 147 #define IOCTL_GNTDEV_DEALLOC_GREF \ 148 _IOW('E', 2, struct ioctl_gntdev_dealloc_gref) 149 struct ioctl_gntdev_dealloc_gref { 150 /* IN parameters */ 151 uint64_t index; 152 uint32_t count; 153 }; 154 155 /*-------------------- Grant Mapping IOCTLs ---------------------------------*/ 156 157 struct ioctl_gntdev_grant_ref { 158 uint32_t domid; 159 uint32_t ref; 160 }; 161 162 #define IOCTL_GNTDEV_MAP_GRANT_REF \ 163 _IOWR('E', 3, struct ioctl_gntdev_map_grant_ref) 164 struct ioctl_gntdev_map_grant_ref { 165 /* IN parameters */ 166 uint32_t count; 167 uint32_t pad0; 168 /* OUT parameters */ 169 uint64_t index; 170 /* Variable IN parameter */ 171 struct ioctl_gntdev_grant_ref *refs; 172 }; 173 174 #define IOCTL_GNTDEV_UNMAP_GRANT_REF \ 175 _IOW('E', 4, struct ioctl_gntdev_unmap_grant_ref) 176 struct ioctl_gntdev_unmap_grant_ref { 177 /* IN parameters */ 178 uint64_t index; 179 uint32_t count; 180 }; 181 182 #define IOCTL_GNTDEV_GET_OFFSET_FOR_VADDR \ 183 _IOWR('E', 5, struct ioctl_gntdev_get_offset_for_vaddr) 184 struct ioctl_gntdev_get_offset_for_vaddr { 185 /* IN parameters */ 186 uint64_t vaddr; 187 /* OUT parameters */ 188 uint64_t offset; 189 uint32_t count; 190 }; 191 192 #endif /* __XEN_GNTDEV_H__ */ 193