xen/interface/xen.h

1 /* SPDX-License-Identifier: MIT */
13 #include "xen-compat.h"
16 #include "arch-x86/xen.h"
18 #include "arch-arm.h"
72  * ` enum hypercall_num { // __HYPERVISOR_* => HYPERVISOR_*()
118 /* Architecture-specific hypercall definitions. */
140 /* New event-channel and physdev hypercalls introduced in 0x00030202. */
158  * In the side comments, 'V.' denotes a per-VCPU VIRQ while 'G.' denotes a
159  * global VIRQ. The former can be bound once per VCPU and cannot be re-bound.
161  * allocated to VCPU0 but can subsequently be re-bound.
163 /* ` enum virq { */
178 /* Architecture-specific VIRQ definitions. */
192  * ` enum neg_errnoval
204  *                     (x) encodes the PFD as follows:
206  *                     x != 0 => PFD == x - 1
208  * Sub-commands: ptr[1:0] specifies the appropriate MMU_* command.
209  * -------------
217  * ptr[:2]  -- Machine address of the page-table entry to modify.
218  * val      -- Value to write.
221  * pages that make up a pagetable must be mapped read-only in the guest.
224  * mapping pagetable page RW, and will disallow using any writable page as a
227  *  1). Start with top-level page (PGD or in Xen language: L4). Fill out
234  *  	PTE table as RO.
244  * For 32-bit guests, the L4 is not used (as there is less pagetables), so
248  * and be trapped by the hypervisor (as the PTE entry is RO).
255  * Updates an entry in the machine->pseudo-physical mapping table.
256  * ptr[:2]  -- Machine address within the frame whose mapping to modify.
258  * val      -- Value to write into the mapping entry.
261  * As MMU_NORMAL_PT_UPDATE above, but A/D bits currently in the PTE are ORed
265  * As MMU_NORMAL_PT_UPDATE above, but @val is not translated though FD
272  *  - 63 if set means No execute (NX)
273  *  - 46-13 the machine frame number
274  *  - 12 available for guest
275  *  - 11 available for guest
276  *  - 10 available for guest
277  *  - 9 available for guest
278  *  - 8 global
279  *  - 7 PAT (PSE is disabled, must use hypercall to make 4MB or 2MB pages)
280  *  - 6 dirty
281  *  - 5 accessed
282  *  - 4 page cached disabled
283  *  - 3 page write through
284  *  - 2 userspace accessible
285  *  - 1 writeable
286  *  - 0 present
290  *  HYPERVISOR_mmuext_op serve as mechanism to set a pagetable to be 4MB
294  *  using it as the Page Attribute Table (PAT) bit - for details on it please
298  *  The PAT MSR is as follows (it is a 64-bit value, each entry is 8 bits):
300  *  +-----+-----+----+----+----+-----+----+----+
301  *  | UC  | UC- | WC | WB | UC | UC- | WC | WB |  <= Linux
302  *  +-----+-----+----+----+----+-----+----+----+
303  *  | UC  | UC- | WT | WB | UC | UC- | WT | WB |  <= BIOS (default when machine boots)
304  *  +-----+-----+----+----+----+-----+----+----+
305  *  | rsv | rsv | WP | WC | UC | UC- | WT | WB |  <= Xen
306  *  +-----+-----+----+----+----+-----+----+----+
316  *  As you can see, the Linux PAT1 translates to PAT4 under Xen. Which means
320  *  caching as:
326  * To make it work with Xen, it needs to translate the WC bit as so:
328  *  PWT (so bit 3 on) --> PAT (so bit 7 is on) and clear bit 3
332  * PAT (bit 7 on) --> PWT (bit 3 on) and clear bit 7.
343  * ` enum neg_errnoval
354  * mfn: Machine frame number to be (un)pinned as a p.t. page.
358  * mfn: Machine frame number of new page-table base to install in MMU.
361  * mfn: Machine frame number of new page-table base to install in MMU
391  * linear_addr: Linear address of LDT base (NB. must be page-aligned).
404 /* ` enum mmuext_cmd { */
429     unsigned int cmd; /* => enum mmuext_cmd */
455  * ` enum neg_errnoval
457  * `                              enum uvm_flags flags)
459  * ` enum neg_errnoval
461  * `                                          enum uvm_flags flags,
466  * ` @flags: Control TLB flushes
468 /* These are passed as 'flags' to update_va_mapping. They can be ORed. */
471 /* ` enum uvm_flags { */
521  * x86 guests: support writes to bottom-level PTEs.
522  * NB1. Page-directory entries cannot be written.
532  *  - virtual iopl updated from do_iret() hypercalls.
533  *  - virtual iopl reported in bounce frames.
534  *  - guest kernels assumed to be level 0 for the purpose of iopl checks.
548  * - when not set, L4 tables get created with the respective slot blank,
549  *   and whenever the L4 table gets used as a kernel one the missing
551  * - when set, L4 tables get created with the respective slot initialized
552  *   as before, and whenever the L4 table gets used as a user one the
568  * DOMID_IO is used to restrict page-table updates to mapping I/O memory.
571  * installed. (e.g., in Linux this could cause havoc as reference counts
572  * aren't adjusted on the I/O-mapping code path).
573  * This only makes sense as HYPERVISOR_mmu_update()'s and
583  * This only makes sense as
584  * - HYPERVISOR_mmu_update()'s, HYPERVISOR_mmuext_op()'s, or
586  * - with XENMAPSPACE_gmfn_foreign,
592  * DOMID_COW is used as the owner of sharable pages */
620  * ` enum neg_errnoval
637  * Event channel endpoints per domain (when using the 2-level ABI):
647      * looking for changes to 'version'. If the least-significant bit of
660      *   ((((tsc - tsc_timestamp) << tsc_shift) * tsc_to_system_mul) >> 32)
667     uint8_t  flags;  member
680      * 'evtchn_upcall_pending' is written non-zero by Xen to indicate
683      * a set-and-check race. Note that the mask is only accessed by Xen
685      * pending and mask flags can be updated by the guest without special
690      *  1. The task of 'interrupt holdoff' is covered by the per-event-
694      *  2. The main purpose of the per-VCPU mask is therefore to restrict
700      * non-zero mask therefore guarantees that the VCPU will not receive
702      * to block: this avoids wakeup-waiting races.
719  * `incontents 200 startofday_shared Start-of-day shared data structure
720  * Xen/kernel shared data -- pointer provided in start_info.
734      *  1. Bi-directional inter- and intra-domain connections. Domains must
735      *     arrange out-of-band to set up a connection (usually by allocating
737      *     such as xenstore).
738      *  2. Physical interrupts. A domain with suitable hardware-access
739      *     privileges can bind an event-channel port to a physical interrupt
741      *  3. Virtual interrupts ('events'). A domain can bind an event-channel
742      *     port to a virtual interrupt source, such as the virtual-timer
747      *  1. PENDING -- notifies the domain that there is a pending notification
749      *  2. MASK -- if this bit is clear then a 0->1 transition of PENDING
751      *     updated by the guest. It is read-only within Xen. If a channel
754      *     pending notifications as no upcall will be scheduled by Xen).
756      * To expedite scanning of pending notifications, any 0->1 pending
758      * per-vcpu selector word to be set. Each bit in the selector covers a
767      * wallclock-base value.
769      * adjusted by the domain's 'time offset' (in seconds) as set either
791  * `incontents 200 startofday Start-of-day memory layout
793  *  1. The domain is started within contiguous virtual-memory region.
807  *  4. Bootstrap elements are packed together, but each is 4kB-aligned.
808  *  5. The list of page frames forms a contiguous 'pseudo-physical' memory
809  *     layout for the domain. In particular, the bootstrap virtual-memory
810  *     region is a 1:1 mapping to the first section of the pseudo-physical map.
811  *  6. All bootstrap elements are mapped read-writable for the guest OS. The
812  *     only exception is the bootstrap page table, which is mapped read-only.
817  * Note: Prior to 25833:bb85bbccb1c9. ("x86/32-on-64 adjust Dom0 initial page
820  * This only manifested itself on 32-on-64 dom0 kernels and not 32-on-64 domU
821  * or 64-bit kernels of any colour. The page tables for a 32-on-64 dom0 got
824  * 32-bit and runs under a 64-bit hypervisor should _NOT_ use two of the
825  * pages preceding pt_base and mark them as reserved/unused.
830     char magic[32];             /* "xen-<version>-<platform>".            */
833     uint32_t flags;             /* SIF_xxx flags.                         */  member
849     unsigned long mfn_list;     /* VIRTUAL address of page-frame list.    */
850     unsigned long mod_start;    /* VIRTUAL address of pre-loaded module   */
851                                 /* (PFN of pre-loaded module if           */
852                                 /*  SIF_MOD_START_PFN set in flags).      */
853     unsigned long mod_len;      /* Size (bytes) of pre-loaded module.     */
856     /* The pfn range here covers both page table and p->m table frames.   */
857     unsigned long first_p2m_pfn;/* 1st pfn forming initial P->M table.    */
858     unsigned long nr_p2m_frames;/* # of pfns forming initial P->M table.  */
869 /* These flags are passed in the 'flags' field of start_info_t. */
875                                    /* P->M making the 3 level tree obsolete? */
876 #define SIF_PM_MASK       (0xFF<<8) /* reserve 1 byte for xen-pm options */
881  * - the array of module descriptors is by convention simply at the beginning
883  * - addresses in the module descriptors are based on the beginning of the
885  * - the number of modules is determined by a termination descriptor that has
898     /* Address of zero-terminated command line */
937             /* RGB mask offsets and sizes, as defined by VBE 1.2+ */
973  * will construct UUID 00112233-4455-6677-8899-aabbccddeeff presented as
978  * compatible with Microsoft, as they use mixed-endian encoding (some
979  * components are little-endian, some are big-endian).
1027  * c-file-style: "BSD"
1028  * c-basic-offset: 4
1029  * tab-width: 4
1030  * indent-tabs-mode: nil