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