1 /* 2 * Copyright (c) 2017 Citrix Systems Inc. 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; 7 * version 2.1 of the License. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; If not, see <http://www.gnu.org/licenses/>. 16 */ 17 #ifndef XENDEVICEMODEL_H 18 #define XENDEVICEMODEL_H 19 20 #ifdef __XEN_TOOLS__ 21 22 #include <stdint.h> 23 24 #include <xen/xen.h> 25 #include <xen/hvm/dm_op.h> 26 #include <xen/hvm/hvm_op.h> 27 28 /* Callers who don't care don't need to #include <xentoollog.h> */ 29 struct xentoollog_logger; 30 31 typedef struct xendevicemodel_handle xendevicemodel_handle; 32 33 xendevicemodel_handle *xendevicemodel_open(struct xentoollog_logger *logger, 34 unsigned int open_flags); 35 36 int xendevicemodel_close(xendevicemodel_handle *dmod); 37 38 /* 39 * IOREQ Server API. (See section on IOREQ Servers in public/hvm_op.h). 40 */ 41 42 /** 43 * This function instantiates an IOREQ Server. 44 * 45 * @parm dmod a handle to an open devicemodel interface. 46 * @parm domid the domain id to be serviced 47 * @parm handle_bufioreq how should the IOREQ Server handle buffered 48 * requests (HVM_IOREQSRV_BUFIOREQ_*)? 49 * @parm id pointer to an ioservid_t to receive the IOREQ Server id. 50 * @return 0 on success, -1 on failure. 51 */ 52 int xendevicemodel_create_ioreq_server( 53 xendevicemodel_handle *dmod, domid_t domid, int handle_bufioreq, 54 ioservid_t *id); 55 56 /** 57 * This function retrieves the necessary information to allow an 58 * emulator to use an IOREQ Server. 59 * 60 * @parm dmod a handle to an open devicemodel interface. 61 * @parm domid the domain id to be serviced 62 * @parm id the IOREQ Server id. 63 * @parm ioreq_gfn pointer to a xen_pfn_t to receive the synchronous ioreq 64 * gfn. (May be NULL if not required) 65 * @parm bufioreq_gfn pointer to a xen_pfn_t to receive the buffered ioreq 66 * gfn. (May be NULL if not required) 67 * @parm bufioreq_port pointer to a evtchn_port_t to receive the buffered 68 * ioreq event channel. (May be NULL if not required) 69 * @return 0 on success, -1 on failure. 70 */ 71 int xendevicemodel_get_ioreq_server_info( 72 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id, 73 xen_pfn_t *ioreq_gfn, xen_pfn_t *bufioreq_gfn, 74 evtchn_port_t *bufioreq_port); 75 76 /** 77 * This function registers a range of memory or I/O ports for emulation. 78 * 79 * @parm dmod a handle to an open devicemodel interface. 80 * @parm domid the domain id to be serviced 81 * @parm id the IOREQ Server id. 82 * @parm is_mmio is this a range of ports or memory 83 * @parm start start of range 84 * @parm end end of range (inclusive). 85 * @return 0 on success, -1 on failure. 86 */ 87 int xendevicemodel_map_io_range_to_ioreq_server( 88 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id, int is_mmio, 89 uint64_t start, uint64_t end); 90 91 /** 92 * This function deregisters a range of memory or I/O ports for emulation. 93 * 94 * @parm dmod a handle to an open devicemodel interface. 95 * @parm domid the domain id to be serviced 96 * @parm id the IOREQ Server id. 97 * @parm is_mmio is this a range of ports or memory 98 * @parm start start of range 99 * @parm end end of range (inclusive). 100 * @return 0 on success, -1 on failure. 101 */ 102 int xendevicemodel_unmap_io_range_from_ioreq_server( 103 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id, int is_mmio, 104 uint64_t start, uint64_t end); 105 106 /** 107 * This function registers/deregisters a memory type for emulation. 108 * 109 * @parm dmod a handle to an open devicemodel interface. 110 * @parm domid the domain id to be serviced. 111 * @parm id the IOREQ Server id. 112 * @parm type the memory type to be emulated. For now, only HVMMEM_ioreq_server 113 * is supported, and in the future new types can be introduced, e.g. 114 * HVMMEM_ioreq_serverX mapped to ioreq server X. 115 * @parm flags operations to be emulated; 0 for unmap. For now, only write 116 * operations will be emulated and can be extended to emulate 117 * read ones in the future. 118 * @return 0 on success, -1 on failure. 119 */ 120 int xendevicemodel_map_mem_type_to_ioreq_server( 121 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id, uint16_t type, 122 uint32_t flags); 123 124 /** 125 * This function registers a PCI device for config space emulation. 126 * 127 * @parm dmod a handle to an open devicemodel interface. 128 * @parm domid the domain id to be serviced 129 * @parm id the IOREQ Server id. 130 * @parm segment the PCI segment of the device 131 * @parm bus the PCI bus of the device 132 * @parm device the 'slot' number of the device 133 * @parm function the function number of the device 134 * @return 0 on success, -1 on failure. 135 */ 136 int xendevicemodel_map_pcidev_to_ioreq_server( 137 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id, 138 uint16_t segment, uint8_t bus, uint8_t device, uint8_t function); 139 140 /** 141 * This function deregisters a PCI device for config space emulation. 142 * 143 * @parm dmod a handle to an open devicemodel interface. 144 * @parm domid the domain id to be serviced 145 * @parm id the IOREQ Server id. 146 * @parm segment the PCI segment of the device 147 * @parm bus the PCI bus of the device 148 * @parm device the 'slot' number of the device 149 * @parm function the function number of the device 150 * @return 0 on success, -1 on failure. 151 */ 152 int xendevicemodel_unmap_pcidev_from_ioreq_server( 153 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id, 154 uint16_t segment, uint8_t bus, uint8_t device, uint8_t function); 155 156 /** 157 * This function destroys an IOREQ Server. 158 * 159 * @parm dmod a handle to an open devicemodel interface. 160 * @parm domid the domain id to be serviced 161 * @parm id the IOREQ Server id. 162 * @return 0 on success, -1 on failure. 163 */ 164 int xendevicemodel_destroy_ioreq_server( 165 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id); 166 167 /** 168 * This function sets IOREQ Server state. An IOREQ Server 169 * will not be passed emulation requests until it is in 170 * the enabled state. 171 * Note that the contents of the ioreq_gfn and bufioreq_gfn are 172 * not meaningful until the IOREQ Server is in the enabled state. 173 * 174 * @parm dmod a handle to an open devicemodel interface. 175 * @parm domid the domain id to be serviced 176 * @parm id the IOREQ Server id. 177 * @parm enabled the state. 178 * @return 0 on success, -1 on failure. 179 */ 180 int xendevicemodel_set_ioreq_server_state( 181 xendevicemodel_handle *dmod, domid_t domid, ioservid_t id, int enabled); 182 183 /** 184 * This function sets the level of INTx pin of an emulated PCI device. 185 * 186 * @parm dmod a handle to an open devicemodel interface. 187 * @parm domid the domain id to be serviced 188 * @parm segment the PCI segment number of the emulated device 189 * @parm bus the PCI bus number of the emulated device 190 * @parm device the PCI device number of the emulated device 191 * @parm intx the INTx pin to modify (0 => A .. 3 => D) 192 * @parm level the level (1 for asserted, 0 for de-asserted) 193 * @return 0 on success, -1 on failure. 194 */ 195 int xendevicemodel_set_pci_intx_level( 196 xendevicemodel_handle *dmod, domid_t domid, uint16_t segment, 197 uint8_t bus, uint8_t device, uint8_t intx, unsigned int level); 198 199 /** 200 * This function sets the level of an ISA IRQ line. 201 * 202 * @parm dmod a handle to an open devicemodel interface. 203 * @parm domid the domain id to be serviced 204 * @parm irq the IRQ number (0 - 15) 205 * @parm level the level (1 for asserted, 0 for de-asserted) 206 * @return 0 on success, -1 on failure. 207 */ 208 int xendevicemodel_set_isa_irq_level( 209 xendevicemodel_handle *dmod, domid_t domid, uint8_t irq, 210 unsigned int level); 211 212 /** 213 * This function maps a PCI INTx line to a an IRQ line. 214 * 215 * @parm dmod a handle to an open devicemodel interface. 216 * @parm domid the domain id to be serviced 217 * @parm line the INTx line (0 => A .. 3 => B) 218 * @parm irq the IRQ number (0 - 15) 219 * @return 0 on success, -1 on failure. 220 */ 221 int xendevicemodel_set_pci_link_route( 222 xendevicemodel_handle *dmod, domid_t domid, uint8_t link, uint8_t irq); 223 224 /** 225 * This function injects an MSI into a guest. 226 * 227 * @parm dmod a handle to an open devicemodel interface. 228 * @parm domid the domain id to be serviced 229 * @parm msi_addr the MSI address (0xfeexxxxx) 230 * @parm msi_data the MSI data 231 * @return 0 on success, -1 on failure. 232 */ 233 int xendevicemodel_inject_msi( 234 xendevicemodel_handle *dmod, domid_t domid, uint64_t msi_addr, 235 uint32_t msi_data); 236 237 /** 238 * This function enables tracking of changes in the VRAM area. 239 * 240 * The following is done atomically: 241 * - get the dirty bitmap since the last call. 242 * - set up dirty tracking area for period up to the next call. 243 * - clear the dirty tracking area. 244 * 245 * @parm dmod a handle to an open devicemodel interface. 246 * @parm domid the domain id to be serviced 247 * @parm first_pfn the start of the area to track 248 * @parm nr the number of pages to track 249 * @parm dirty_bitmal a pointer to the bitmap to be updated 250 * @return 0 on success, -1 on failure. 251 */ 252 int xendevicemodel_track_dirty_vram( 253 xendevicemodel_handle *dmod, domid_t domid, uint64_t first_pfn, 254 uint32_t nr, unsigned long *dirty_bitmap); 255 256 /** 257 * This function notifies the hypervisor that a set of contiguous 258 * domain pages have been modified. 259 * 260 * @parm dmod a handle to an open devicemodel interface. 261 * @parm domid the domain id to be serviced 262 * @parm first_pfn the start of the modified area 263 * @parm nr the number of pages modified 264 * @return 0 on success, -1 on failure. 265 */ 266 int xendevicemodel_modified_memory( 267 xendevicemodel_handle *dmod, domid_t domid, uint64_t first_pfn, 268 uint32_t nr); 269 270 /** 271 * This function notifies the hypervisor that a set of discontiguous 272 * domain pages have been modified. 273 * 274 * @parm dmod a handle to an open devicemodel interface. 275 * @parm domid the domain id to be serviced 276 * @parm extents an array of extent structs, which each hold 277 a start_pfn and nr (number of pfns). 278 * @parm nr the number of extents in the array 279 * @return 0 on success, -1 on failure. 280 */ 281 int xendevicemodel_modified_memory_bulk( 282 xendevicemodel_handle *dmod, domid_t domid, 283 struct xen_dm_op_modified_memory_extent extents[], uint32_t nr); 284 285 /** 286 * This function notifies the hypervisor that a set of domain pages 287 * are to be treated in a specific way. (See the definition of 288 * hvmmem_type_t). 289 * 290 * @parm dmod a handle to an open devicemodel interface. 291 * @parm domid the domain id to be serviced 292 * @parm mem_type determines how the set is to be treated 293 * @parm first_pfn the start of the set 294 * @parm nr the number of pages in the set 295 * @return 0 on success, -1 on failure. 296 */ 297 int xendevicemodel_set_mem_type( 298 xendevicemodel_handle *dmod, domid_t domid, hvmmem_type_t mem_type, 299 uint64_t first_pfn, uint32_t nr); 300 301 /** 302 * This function injects an event into a vCPU to take effect the next 303 * time it resumes. 304 * 305 * @parm dmod a handle to an open devicemodel interface. 306 * @parm domid the domain id to be serviced 307 * @parm vcpu the vcpu id 308 * @parm vector the interrupt vector 309 * @parm type the event type (see the definition of enum x86_event_type) 310 * @parm error_code the error code or ~0 to skip 311 * @parm insn_len the instruction length 312 * @parm extra type-specific extra data (%cr2 for #PF, pending_dbg for #DB) 313 * @return 0 on success, -1 on failure. 314 */ 315 int xendevicemodel_inject_event( 316 xendevicemodel_handle *dmod, domid_t domid, int vcpu, uint8_t vector, 317 uint8_t type, uint32_t error_code, uint8_t insn_len, uint64_t extra); 318 319 /** 320 * Shuts the domain down. 321 * 322 * @parm reason usually enum sched_shutdown_reason, see xen/sched.h 323 * @return 0 on success, -1 on failure. 324 */ 325 int xendevicemodel_shutdown( 326 xendevicemodel_handle *dmod, domid_t domid, unsigned int reason); 327 328 /* 329 * Relocate GFNs for the specified domain. 330 * 331 * @parm dmod a handle to an open devicemodel interface. 332 * @parm domid the domain id to be serviced 333 * @parm size Number of GFNs to process 334 * @parm src_gfn Starting GFN to relocate 335 * @parm dst_gfn Starting GFN where GFNs should be relocated 336 * @return 0 on success, -1 on failure. 337 */ 338 int xendevicemodel_relocate_memory( 339 xendevicemodel_handle *dmod, domid_t domid, uint32_t size, uint64_t src_gfn, 340 uint64_t dst_gfn); 341 342 /** 343 * Pins caching type of RAM space. 344 * 345 * @parm dmod a handle to an open devicemodel interface. 346 * @parm domid the domain id to be serviced 347 * @parm start Start gfn 348 * @parm end End gfn 349 * @parm type XEN_DMOP_MEM_CACHEATTR_* 350 * @return 0 on success, -1 on failure. 351 */ 352 int xendevicemodel_pin_memory_cacheattr( 353 xendevicemodel_handle *dmod, domid_t domid, uint64_t start, uint64_t end, 354 uint32_t type); 355 356 /** 357 * This function restricts the use of this handle to the specified 358 * domain. 359 * 360 * @parm dmod handle to the open devicemodel interface 361 * @parm domid the domain id 362 * @return 0 on success, -1 on failure. 363 */ 364 int xendevicemodel_restrict(xendevicemodel_handle *dmod, domid_t domid); 365 366 #endif /* __XEN_TOOLS__ */ 367 368 #endif /* XENDEVICEMODEL_H */ 369 370 /* 371 * Local variables: 372 * mode: C 373 * c-file-style: "BSD" 374 * c-basic-offset: 4 375 * tab-width: 4 376 * indent-tabs-mode: nil 377 * End: 378 */ 379