xen/interface/xen.h

1 /* SPDX-License-Identifier: MIT */
5  * Guest OS interface to Xen.
69 /* Architecture-specific hypercall definitions. */
82  * Virtual interrupts that a guest OS may receive from Xen.
83  * In the side comments, 'V.' denotes a per-VCPU VIRQ while 'G.' denotes a
84  * global VIRQ. The former can be bound once per VCPU and cannot be re-bound.
85  * The latter can be allocated only once per guest: they must initially be
86  * allocated to VCPU0 but can subsequently be re-bound.
89 #define VIRQ_DEBUG      1  /* V. Request guest to dump debug info.           */
102 /* Architecture-specific VIRQ definitions. */
127  *                     x != 0 => PFD == x - 1
129  * Sub-commands: ptr[1:0] specifies the appropriate MMU_* command.
130  * -------------
138  * ptr[:2]  -- Machine address of the page-table entry to modify.
139  * val      -- Value to write.
142  * pages that make up a pagetable must be mapped read-only in the guest.
143  * This prevents uncontrolled guest updates to the pagetable. Xen strictly
148  *  1). Start with top-level page (PGD or in Xen language: L4). Fill out
161  *      via the HYPERVISOR_mmuext_op(MMUEXT_PIN_L4_TABLE, guest physical frame
163  *      MMUEXT_NEW_BASEPTR, guest physical frame number of the PGD (L4)) can be
165  * For 32-bit guests, the L4 is not used (as there is less pagetables), so
176  * Updates an entry in the machine->pseudo-physical mapping table.
177  * ptr[:2]  -- Machine address within the frame whose mapping to modify.
179  * val      -- Value to write into the mapping entry.
182  * As MMU_NORMAL_PT_UPDATE above, but A/D bits currently in the PTE are ORed
186  * The attributes by default follow the architecture defined bits. Meaning that
189  *  - 63 if set means No execute (NX)
190  *  - 46-13 the machine frame number
191  *  - 12 available for guest
192  *  - 11 available for guest
193  *  - 10 available for guest
194  *  - 9 available for guest
195  *  - 8 global
196  *  - 7 PAT (PSE is disabled, must use hypercall to make 4MB or 2MB pages)
197  *  - 6 dirty
198  *  - 5 accessed
199  *  - 4 page cached disabled
200  *  - 3 page write through
201  *  - 2 userspace accessible
202  *  - 1 writeable
203  *  - 0 present
205  *  The one bits that does not fit with the default layout is the PAGE_PSE
211  *  using it as the Page Attribute Table (PAT) bit - for details on it please
215  *  The PAT MSR is as follows (it is a 64-bit value, each entry is 8 bits):
217  *  +-----+-----+----+----+----+-----+----+----+
218  *  | UC  | UC- | WC | WB | UC | UC- | WC | WB |  <= Linux
219  *  +-----+-----+----+----+----+-----+----+----+
220  *  | UC  | UC- | WT | WB | UC | UC- | WT | WB |  <= BIOS (default when machine boots)
221  *  +-----+-----+----+----+----+-----+----+----+
222  *  | rsv | rsv | WP | WC | UC | UC- | WT | WB |  <= Xen
223  *  +-----+-----+----+----+----+-----+----+----+
225  *  The lookup of this index table translates to looking up
230  *  If all bits are off, then we are using PAT0. If bit 3 turned on,
234  *  that if a guest that follows Linux's PAT setup and would like to set Write
245  *  PWT (so bit 3 on) --> PAT (so bit 7 is on) and clear bit 3
249  * PAT (bit 7 on) --> PWT (bit 3 on) and clear bit 7.
273  * mfn: Machine frame number of new page-table base to install in MMU.
276  * mfn: Machine frame number of new page-table base to install in MMU
306  * linear_addr: Linear address of LDT base (NB. must be page-aligned).
392  * x86 guests: support writes to bottom-level PTEs.
393  * NB1. Page-directory entries cannot be written.
394  * NB2. Guest must continue to remove all writable mappings of PTEs.
403  *  - virtual iopl updated from do_iret() hypercalls.
404  *  - virtual iopl reported in bounce frames.
405  *  - guest kernels assumed to be level 0 for the purpose of iopl checks.
411  * Enable setting the XEN_RUNSTATE_UPDATE flag in guest memory mapped
429  * DOMID_IO is used to restrict page-table updates to mapping I/O memory.
433  * aren't adjusted on the I/O-mapping code path).
470  * any unused bits in the upper portion must be zero.
482 	 * by an increment of 'version'. The guest can therefore
484 	 * least-significant bit of the version number is set then an
485 	 * update is in progress and the guest must wait to read a
496 	 *   system_time + ((tsc - tsc_timestamp) << tsc_shift) * tsc_to_system_mul
507 	 * 'evtchn_upcall_pending' is written non-zero by Xen to indicate
509 	 * by the guest OS /before/ checking for pending work, thus avoiding
510 	 * a set-and-check race. Note that the mask is only accessed by Xen
512 	 * pending and mask flags can be updated by the guest without special
517 	 *  1. The task of 'interrupt holdoff' is covered by the per-event-
518 	 *     channel mask bits. A 'noisy' event that is continually being
521 	 *  2. The main purpose of the per-VCPU mask is therefore to restrict
526 	 * The mask is read before making an event upcall to the guest: a
527 	 * non-zero mask therefore guarantees that the VCPU will not receive
529 	 * to block: this avoids wakeup-waiting races.
539  * Xen/kernel shared data -- pointer provided in start_info.
549 	 *  1. Bi-directional inter- and intra-domain connections. Domains must
550 	 *     arrange out-of-band to set up a connection (usually by allocating
553 	 *  2. Physical interrupts. A domain with suitable hardware-access
554 	 *     privileges can bind an event-channel port to a physical interrupt
556 	 *  3. Virtual interrupts ('events'). A domain can bind an event-channel
557 	 *     port to a virtual interrupt source, such as the virtual-timer
560 	 * Event channels are addressed by a "port index". Each channel is
561 	 * associated with two bits of information:
562 	 *  1. PENDING -- notifies the domain that there is a pending notification
563 	 *     to be processed. This bit is cleared by the guest.
564 	 *  2. MASK -- if this bit is clear then a 0->1 transition of PENDING
566 	 *     updated by the guest. It is read-only within Xen. If a channel
568 	 *     (i.e., when the channel is unmasked, the guest must manually handle
571 	 * To expedite scanning of pending notifications, any 0->1 pending
573 	 * per-vcpu selector word to be set. Each bit in the selector covers a
581 	 * their gettimeofday() syscall on this wallclock-base value.
592  * Start-of-day memory layout
594  *  1. The domain is started within contiguous virtual-memory region.
608  *  4. Bootstrap elements are packed together, but each is 4kB-aligned.
609  *  5. The list of page frames forms a contiguous 'pseudo-physical' memory
610  *     layout for the domain. In particular, the bootstrap virtual-memory
611  *     region is a 1:1 mapping to the first section of the pseudo-physical map.
612  *  6. All bootstrap elements are mapped read-writable for the guest OS. The
613  *     only exception is the bootstrap page table, which is mapped read-only.
622 	char magic[32];             /* "xen-<version>-<platform>".            */
641 	unsigned long mfn_list;     /* VIRTUAL address of page-frame list.    */
642 	unsigned long mod_start;    /* VIRTUAL address of pre-loaded module.  */
643 	unsigned long mod_len;      /* Size (bytes) of pre-loaded module.     */
645 	/* The pfn range here covers both page table and p->m table frames.   */
646 	unsigned long first_p2m_pfn;/* 1st pfn forming initial P->M table.    */
647 	unsigned long nr_p2m_frames;/* # of pfns forming initial P->M table.  */
656 				    /* P->M making the 3 level tree obsolete? */
657 #define SIF_PM_MASK       (0xFF<<8) /* reserve 1 byte for xen-pm options */
662  * - the array of module descriptors is by convention simply at the beginning
664  * - addresses in the module descriptors are based on the beginning of the
666  * - the number of modules is determined by a termination descriptor that has
670  * file, and let the PV guest easily rebase the addresses to virtual addresses
678 	/* Address of zero-terminated command line */
710 			/* Bits per pixel. */
726 			/* high 32 bits of lfb_base */
752 			uint32_t index;  member
756 			GUEST_HANDLE(void) gmfn; /* guest machine page frame */