iPXE
hvm_op.h
Go to the documentation of this file.
00001 /*
00002  * Permission is hereby granted, free of charge, to any person obtaining a copy
00003  * of this software and associated documentation files (the "Software"), to
00004  * deal in the Software without restriction, including without limitation the
00005  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
00006  * sell copies of the Software, and to permit persons to whom the Software is
00007  * furnished to do so, subject to the following conditions:
00008  *
00009  * The above copyright notice and this permission notice shall be included in
00010  * all copies or substantial portions of the Software.
00011  *
00012  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00013  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00014  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00015  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00016  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00017  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00018  * DEALINGS IN THE SOFTWARE.
00019  */
00020 
00021 #ifndef __XEN_PUBLIC_HVM_HVM_OP_H__
00022 #define __XEN_PUBLIC_HVM_HVM_OP_H__
00023 
00024 FILE_LICENCE ( MIT );
00025 
00026 #include "../xen.h"
00027 #include "../trace.h"
00028 #include "../event_channel.h"
00029 
00030 /* Get/set subcommands: extra argument == pointer to xen_hvm_param struct. */
00031 #define HVMOP_set_param           0
00032 #define HVMOP_get_param           1
00033 struct xen_hvm_param {
00034     domid_t  domid;    /* IN */
00035     uint32_t index;    /* IN */
00036     uint64_t value;    /* IN/OUT */
00037 };
00038 typedef struct xen_hvm_param xen_hvm_param_t;
00039 DEFINE_XEN_GUEST_HANDLE(xen_hvm_param_t);
00040 
00041 /* Set the logical level of one of a domain's PCI INTx wires. */
00042 #define HVMOP_set_pci_intx_level  2
00043 struct xen_hvm_set_pci_intx_level {
00044     /* Domain to be updated. */
00045     domid_t  domid;
00046     /* PCI INTx identification in PCI topology (domain:bus:device:intx). */
00047     uint8_t  domain, bus, device, intx;
00048     /* Assertion level (0 = unasserted, 1 = asserted). */
00049     uint8_t  level;
00050 };
00051 typedef struct xen_hvm_set_pci_intx_level xen_hvm_set_pci_intx_level_t;
00052 DEFINE_XEN_GUEST_HANDLE(xen_hvm_set_pci_intx_level_t);
00053 
00054 /* Set the logical level of one of a domain's ISA IRQ wires. */
00055 #define HVMOP_set_isa_irq_level   3
00056 struct xen_hvm_set_isa_irq_level {
00057     /* Domain to be updated. */
00058     domid_t  domid;
00059     /* ISA device identification, by ISA IRQ (0-15). */
00060     uint8_t  isa_irq;
00061     /* Assertion level (0 = unasserted, 1 = asserted). */
00062     uint8_t  level;
00063 };
00064 typedef struct xen_hvm_set_isa_irq_level xen_hvm_set_isa_irq_level_t;
00065 DEFINE_XEN_GUEST_HANDLE(xen_hvm_set_isa_irq_level_t);
00066 
00067 #define HVMOP_set_pci_link_route  4
00068 struct xen_hvm_set_pci_link_route {
00069     /* Domain to be updated. */
00070     domid_t  domid;
00071     /* PCI link identifier (0-3). */
00072     uint8_t  link;
00073     /* ISA IRQ (1-15), or 0 (disable link). */
00074     uint8_t  isa_irq;
00075 };
00076 typedef struct xen_hvm_set_pci_link_route xen_hvm_set_pci_link_route_t;
00077 DEFINE_XEN_GUEST_HANDLE(xen_hvm_set_pci_link_route_t);
00078 
00079 /* Flushes all VCPU TLBs: @arg must be NULL. */
00080 #define HVMOP_flush_tlbs          5
00081 
00082 typedef enum {
00083     HVMMEM_ram_rw,             /* Normal read/write guest RAM */
00084     HVMMEM_ram_ro,             /* Read-only; writes are discarded */
00085     HVMMEM_mmio_dm,            /* Reads and write go to the device model */
00086 } hvmmem_type_t;
00087 
00088 /* Following tools-only interfaces may change in future. */
00089 #if defined(__XEN__) || defined(__XEN_TOOLS__)
00090 
00091 /* Track dirty VRAM. */
00092 #define HVMOP_track_dirty_vram    6
00093 struct xen_hvm_track_dirty_vram {
00094     /* Domain to be tracked. */
00095     domid_t  domid;
00096     /* Number of pages to track. */
00097     uint32_t nr;
00098     /* First pfn to track. */
00099     uint64_aligned_t first_pfn;
00100     /* OUT variable. */
00101     /* Dirty bitmap buffer. */
00102     XEN_GUEST_HANDLE_64(uint8) dirty_bitmap;
00103 };
00104 typedef struct xen_hvm_track_dirty_vram xen_hvm_track_dirty_vram_t;
00105 DEFINE_XEN_GUEST_HANDLE(xen_hvm_track_dirty_vram_t);
00106 
00107 /* Notify that some pages got modified by the Device Model. */
00108 #define HVMOP_modified_memory    7
00109 struct xen_hvm_modified_memory {
00110     /* Domain to be updated. */
00111     domid_t  domid;
00112     /* Number of pages. */
00113     uint32_t nr;
00114     /* First pfn. */
00115     uint64_aligned_t first_pfn;
00116 };
00117 typedef struct xen_hvm_modified_memory xen_hvm_modified_memory_t;
00118 DEFINE_XEN_GUEST_HANDLE(xen_hvm_modified_memory_t);
00119 
00120 #define HVMOP_set_mem_type    8
00121 /* Notify that a region of memory is to be treated in a specific way. */
00122 struct xen_hvm_set_mem_type {
00123     /* Domain to be updated. */
00124     domid_t domid;
00125     /* Memory type */
00126     uint16_t hvmmem_type;
00127     /* Number of pages. */
00128     uint32_t nr;
00129     /* First pfn. */
00130     uint64_aligned_t first_pfn;
00131 };
00132 typedef struct xen_hvm_set_mem_type xen_hvm_set_mem_type_t;
00133 DEFINE_XEN_GUEST_HANDLE(xen_hvm_set_mem_type_t);
00134 
00135 #endif /* defined(__XEN__) || defined(__XEN_TOOLS__) */
00136 
00137 /* Hint from PV drivers for pagetable destruction. */
00138 #define HVMOP_pagetable_dying        9
00139 struct xen_hvm_pagetable_dying {
00140     /* Domain with a pagetable about to be destroyed. */
00141     domid_t  domid;
00142     uint16_t pad[3]; /* align next field on 8-byte boundary */
00143     /* guest physical address of the toplevel pagetable dying */
00144     uint64_t gpa;
00145 };
00146 typedef struct xen_hvm_pagetable_dying xen_hvm_pagetable_dying_t;
00147 DEFINE_XEN_GUEST_HANDLE(xen_hvm_pagetable_dying_t);
00148 
00149 /* Get the current Xen time, in nanoseconds since system boot. */
00150 #define HVMOP_get_time              10
00151 struct xen_hvm_get_time {
00152     uint64_t now;      /* OUT */
00153 };
00154 typedef struct xen_hvm_get_time xen_hvm_get_time_t;
00155 DEFINE_XEN_GUEST_HANDLE(xen_hvm_get_time_t);
00156 
00157 #define HVMOP_xentrace              11
00158 struct xen_hvm_xentrace {
00159     uint16_t event, extra_bytes;
00160     uint8_t extra[TRACE_EXTRA_MAX * sizeof(uint32_t)];
00161 };
00162 typedef struct xen_hvm_xentrace xen_hvm_xentrace_t;
00163 DEFINE_XEN_GUEST_HANDLE(xen_hvm_xentrace_t);
00164 
00165 /* Following tools-only interfaces may change in future. */
00166 #if defined(__XEN__) || defined(__XEN_TOOLS__)
00167 
00168 /* Deprecated by XENMEM_access_op_set_access */
00169 #define HVMOP_set_mem_access        12
00170 
00171 /* Deprecated by XENMEM_access_op_get_access */
00172 #define HVMOP_get_mem_access        13
00173 
00174 #define HVMOP_inject_trap            14
00175 /* Inject a trap into a VCPU, which will get taken up on the next
00176  * scheduling of it. Note that the caller should know enough of the
00177  * state of the CPU before injecting, to know what the effect of
00178  * injecting the trap will be.
00179  */
00180 struct xen_hvm_inject_trap {
00181     /* Domain to be queried. */
00182     domid_t domid;
00183     /* VCPU */
00184     uint32_t vcpuid;
00185     /* Vector number */
00186     uint32_t vector;
00187     /* Trap type (HVMOP_TRAP_*) */
00188     uint32_t type;
00189 /* NB. This enumeration precisely matches hvm.h:X86_EVENTTYPE_* */
00190 # define HVMOP_TRAP_ext_int    0 /* external interrupt */
00191 # define HVMOP_TRAP_nmi        2 /* nmi */
00192 # define HVMOP_TRAP_hw_exc     3 /* hardware exception */
00193 # define HVMOP_TRAP_sw_int     4 /* software interrupt (CD nn) */
00194 # define HVMOP_TRAP_pri_sw_exc 5 /* ICEBP (F1) */
00195 # define HVMOP_TRAP_sw_exc     6 /* INT3 (CC), INTO (CE) */
00196     /* Error code, or ~0u to skip */
00197     uint32_t error_code;
00198     /* Intruction length */
00199     uint32_t insn_len;
00200     /* CR2 for page faults */
00201     uint64_aligned_t cr2;
00202 };
00203 typedef struct xen_hvm_inject_trap xen_hvm_inject_trap_t;
00204 DEFINE_XEN_GUEST_HANDLE(xen_hvm_inject_trap_t);
00205 
00206 #endif /* defined(__XEN__) || defined(__XEN_TOOLS__) */
00207 
00208 #define HVMOP_get_mem_type    15
00209 /* Return hvmmem_type_t for the specified pfn. */
00210 struct xen_hvm_get_mem_type {
00211     /* Domain to be queried. */
00212     domid_t domid;
00213     /* OUT variable. */
00214     uint16_t mem_type;
00215     uint16_t pad[2]; /* align next field on 8-byte boundary */
00216     /* IN variable. */
00217     uint64_t pfn;
00218 };
00219 typedef struct xen_hvm_get_mem_type xen_hvm_get_mem_type_t;
00220 DEFINE_XEN_GUEST_HANDLE(xen_hvm_get_mem_type_t);
00221 
00222 /* Following tools-only interfaces may change in future. */
00223 #if defined(__XEN__) || defined(__XEN_TOOLS__)
00224 
00225 /* MSI injection for emulated devices */
00226 #define HVMOP_inject_msi         16
00227 struct xen_hvm_inject_msi {
00228     /* Domain to be injected */
00229     domid_t   domid;
00230     /* Data -- lower 32 bits */
00231     uint32_t  data;
00232     /* Address (0xfeexxxxx) */
00233     uint64_t  addr;
00234 };
00235 typedef struct xen_hvm_inject_msi xen_hvm_inject_msi_t;
00236 DEFINE_XEN_GUEST_HANDLE(xen_hvm_inject_msi_t);
00237 
00238 /*
00239  * IOREQ Servers
00240  *
00241  * The interface between an I/O emulator an Xen is called an IOREQ Server.
00242  * A domain supports a single 'legacy' IOREQ Server which is instantiated if
00243  * parameter...
00244  *
00245  * HVM_PARAM_IOREQ_PFN is read (to get the gmfn containing the synchronous
00246  * ioreq structures), or...
00247  * HVM_PARAM_BUFIOREQ_PFN is read (to get the gmfn containing the buffered
00248  * ioreq ring), or...
00249  * HVM_PARAM_BUFIOREQ_EVTCHN is read (to get the event channel that Xen uses
00250  * to request buffered I/O emulation).
00251  *
00252  * The following hypercalls facilitate the creation of IOREQ Servers for
00253  * 'secondary' emulators which are invoked to implement port I/O, memory, or
00254  * PCI config space ranges which they explicitly register.
00255  */
00256 
00257 typedef uint16_t ioservid_t;
00258 
00259 /*
00260  * HVMOP_create_ioreq_server: Instantiate a new IOREQ Server for a secondary
00261  *                            emulator servicing domain <domid>.
00262  *
00263  * The <id> handed back is unique for <domid>. If <handle_bufioreq> is zero
00264  * the buffered ioreq ring will not be allocated and hence all emulation
00265  * requestes to this server will be synchronous.
00266  */
00267 #define HVMOP_create_ioreq_server 17
00268 struct xen_hvm_create_ioreq_server {
00269     domid_t domid;           /* IN - domain to be serviced */
00270     uint8_t handle_bufioreq; /* IN - should server handle buffered ioreqs */
00271     ioservid_t id;           /* OUT - server id */
00272 };
00273 typedef struct xen_hvm_create_ioreq_server xen_hvm_create_ioreq_server_t;
00274 DEFINE_XEN_GUEST_HANDLE(xen_hvm_create_ioreq_server_t);
00275 
00276 /*
00277  * HVMOP_get_ioreq_server_info: Get all the information necessary to access
00278  *                              IOREQ Server <id>.
00279  *
00280  * The emulator needs to map the synchronous ioreq structures and buffered
00281  * ioreq ring (if it exists) that Xen uses to request emulation. These are
00282  * hosted in domain <domid>'s gmfns <ioreq_pfn> and <bufioreq_pfn>
00283  * respectively. In addition, if the IOREQ Server is handling buffered
00284  * emulation requests, the emulator needs to bind to event channel
00285  * <bufioreq_port> to listen for them. (The event channels used for
00286  * synchronous emulation requests are specified in the per-CPU ioreq
00287  * structures in <ioreq_pfn>).
00288  * If the IOREQ Server is not handling buffered emulation requests then the
00289  * values handed back in <bufioreq_pfn> and <bufioreq_port> will both be 0.
00290  */
00291 #define HVMOP_get_ioreq_server_info 18
00292 struct xen_hvm_get_ioreq_server_info {
00293     domid_t domid;                 /* IN - domain to be serviced */
00294     ioservid_t id;                 /* IN - server id */
00295     evtchn_port_t bufioreq_port;   /* OUT - buffered ioreq port */
00296     uint64_aligned_t ioreq_pfn;    /* OUT - sync ioreq pfn */
00297     uint64_aligned_t bufioreq_pfn; /* OUT - buffered ioreq pfn */
00298 };
00299 typedef struct xen_hvm_get_ioreq_server_info xen_hvm_get_ioreq_server_info_t;
00300 DEFINE_XEN_GUEST_HANDLE(xen_hvm_get_ioreq_server_info_t);
00301 
00302 /*
00303  * HVM_map_io_range_to_ioreq_server: Register an I/O range of domain <domid>
00304  *                                   for emulation by the client of IOREQ
00305  *                                   Server <id>
00306  * HVM_unmap_io_range_from_ioreq_server: Deregister an I/O range of <domid>
00307  *                                       for emulation by the client of IOREQ
00308  *                                       Server <id>
00309  *
00310  * There are three types of I/O that can be emulated: port I/O, memory accesses
00311  * and PCI config space accesses. The <type> field denotes which type of range
00312  * the <start> and <end> (inclusive) fields are specifying.
00313  * PCI config space ranges are specified by segment/bus/device/function values
00314  * which should be encoded using the HVMOP_PCI_SBDF helper macro below.
00315  *
00316  * NOTE: unless an emulation request falls entirely within a range mapped
00317  * by a secondary emulator, it will not be passed to that emulator.
00318  */
00319 #define HVMOP_map_io_range_to_ioreq_server 19
00320 #define HVMOP_unmap_io_range_from_ioreq_server 20
00321 struct xen_hvm_io_range {
00322     domid_t domid;               /* IN - domain to be serviced */
00323     ioservid_t id;               /* IN - server id */
00324     uint32_t type;               /* IN - type of range */
00325 # define HVMOP_IO_RANGE_PORT   0 /* I/O port range */
00326 # define HVMOP_IO_RANGE_MEMORY 1 /* MMIO range */
00327 # define HVMOP_IO_RANGE_PCI    2 /* PCI segment/bus/dev/func range */
00328     uint64_aligned_t start, end; /* IN - inclusive start and end of range */
00329 };
00330 typedef struct xen_hvm_io_range xen_hvm_io_range_t;
00331 DEFINE_XEN_GUEST_HANDLE(xen_hvm_io_range_t);
00332 
00333 #define HVMOP_PCI_SBDF(s,b,d,f)                 \
00334         ((((s) & 0xffff) << 16) |                   \
00335          (((b) & 0xff) << 8) |                      \
00336          (((d) & 0x1f) << 3) |                      \
00337          ((f) & 0x07))
00338 
00339 /*
00340  * HVMOP_destroy_ioreq_server: Destroy the IOREQ Server <id> servicing domain
00341  *                             <domid>.
00342  *
00343  * Any registered I/O ranges will be automatically deregistered.
00344  */
00345 #define HVMOP_destroy_ioreq_server 21
00346 struct xen_hvm_destroy_ioreq_server {
00347     domid_t domid; /* IN - domain to be serviced */
00348     ioservid_t id; /* IN - server id */
00349 };
00350 typedef struct xen_hvm_destroy_ioreq_server xen_hvm_destroy_ioreq_server_t;
00351 DEFINE_XEN_GUEST_HANDLE(xen_hvm_destroy_ioreq_server_t);
00352 
00353 /*
00354  * HVMOP_set_ioreq_server_state: Enable or disable the IOREQ Server <id> servicing
00355  *                               domain <domid>.
00356  *
00357  * The IOREQ Server will not be passed any emulation requests until it is in the
00358  * enabled state.
00359  * Note that the contents of the ioreq_pfn and bufioreq_fn (see
00360  * HVMOP_get_ioreq_server_info) are not meaningful until the IOREQ Server is in
00361  * the enabled state.
00362  */
00363 #define HVMOP_set_ioreq_server_state 22
00364 struct xen_hvm_set_ioreq_server_state {
00365     domid_t domid;   /* IN - domain to be serviced */
00366     ioservid_t id;   /* IN - server id */
00367     uint8_t enabled; /* IN - enabled? */
00368 };
00369 typedef struct xen_hvm_set_ioreq_server_state xen_hvm_set_ioreq_server_state_t;
00370 DEFINE_XEN_GUEST_HANDLE(xen_hvm_set_ioreq_server_state_t);
00371 
00372 #endif /* defined(__XEN__) || defined(__XEN_TOOLS__) */
00373 
00374 #endif /* __XEN_PUBLIC_HVM_HVM_OP_H__ */
00375 
00376 /*
00377  * Local variables:
00378  * mode: C
00379  * c-file-style: "BSD"
00380  * c-basic-offset: 4
00381  * tab-width: 4
00382  * indent-tabs-mode: nil
00383  * End:
00384  */