include/xen/interface/xen.h

   1 /* SPDX-License-Identifier: MIT
   2  *
   3  * xen.h
   4  *
   5  * Guest OS interface to Xen.
   6  *
   7  * Copyright (c) 2004, K A Fraser
   8  */
   9
  10 #ifndef __XEN_PUBLIC_XEN_H__
  11 #define __XEN_PUBLIC_XEN_H__
  12
  13 #include <xen/arm/interface.h>
  14
  15 /*
  16  * XEN "SYSTEM CALLS" (a.k.a. HYPERCALLS).
  17  */
  18
  19 /*
  20  * x86_32: EAX = vector; EBX, ECX, EDX, ESI, EDI = args 1, 2, 3, 4, 5.
  21  *         EAX = return value
  22  *         (argument registers may be clobbered on return)
  23  * x86_64: RAX = vector; RDI, RSI, RDX, R10, R8, R9 = args 1, 2, 3, 4, 5, 6.
  24  *         RAX = return value
  25  *         (argument registers not clobbered on return; RCX, R11 are)
  26  */
  27 #define __HYPERVISOR_set_trap_table        0
  28 #define __HYPERVISOR_mmu_update            1
  29 #define __HYPERVISOR_set_gdt               2
  30 #define __HYPERVISOR_stack_switch          3
  31 #define __HYPERVISOR_set_callbacks         4
  32 #define __HYPERVISOR_fpu_taskswitch        5
  33 #define __HYPERVISOR_sched_op_compat       6
  34 #define __HYPERVISOR_platform_op           7
  35 #define __HYPERVISOR_set_debugreg          8
  36 #define __HYPERVISOR_get_debugreg          9
  37 #define __HYPERVISOR_update_descriptor    10
  38 #define __HYPERVISOR_memory_op            12
  39 #define __HYPERVISOR_multicall            13
  40 #define __HYPERVISOR_update_va_mapping    14
  41 #define __HYPERVISOR_set_timer_op         15
  42 #define __HYPERVISOR_event_channel_op_compat 16
  43 #define __HYPERVISOR_xen_version          17
  44 #define __HYPERVISOR_console_io           18
  45 #define __HYPERVISOR_physdev_op_compat    19
  46 #define __HYPERVISOR_grant_table_op       20
  47 #define __HYPERVISOR_vm_assist            21
  48 #define __HYPERVISOR_update_va_mapping_otherdomain 22
  49 #define __HYPERVISOR_iret                 23 /* x86 only */
  50 #define __HYPERVISOR_vcpu_op              24
  51 #define __HYPERVISOR_set_segment_base     25 /* x86/64 only */
  52 #define __HYPERVISOR_mmuext_op            26
  53 #define __HYPERVISOR_xsm_op               27
  54 #define __HYPERVISOR_nmi_op               28
  55 #define __HYPERVISOR_sched_op             29
  56 #define __HYPERVISOR_callback_op          30
  57 #define __HYPERVISOR_xenoprof_op          31
  58 #define __HYPERVISOR_event_channel_op     32
  59 #define __HYPERVISOR_physdev_op           33
  60 #define __HYPERVISOR_hvm_op               34
  61 #define __HYPERVISOR_sysctl               35
  62 #define __HYPERVISOR_domctl               36
  63 #define __HYPERVISOR_kexec_op             37
  64 #define __HYPERVISOR_tmem_op              38
  65 #define __HYPERVISOR_xc_reserved_op       39 /* reserved for XenClient */
  66 #define __HYPERVISOR_xenpmu_op            40
  67 #define __HYPERVISOR_dm_op                41
  68
  69 /* Architecture-specific hypercall definitions. */
  70 #define __HYPERVISOR_arch_0               48
  71 #define __HYPERVISOR_arch_1               49
  72 #define __HYPERVISOR_arch_2               50
  73 #define __HYPERVISOR_arch_3               51
  74 #define __HYPERVISOR_arch_4               52
  75 #define __HYPERVISOR_arch_5               53
  76 #define __HYPERVISOR_arch_6               54
  77 #define __HYPERVISOR_arch_7               55
  78
  79 /*
  80  * Commands to HYPERVISOR_console_io().
  81  */
  82 #define CONSOLEIO_write         0
  83 #define CONSOLEIO_read          1
  84
  85 #ifndef __ASSEMBLY__
  86
  87 typedef u16 domid_t;
  88
  89 /* Domain ids >= DOMID_FIRST_RESERVED cannot be used for ordinary domains. */
  90 #define DOMID_FIRST_RESERVED (0x7FF0U)
  91
  92 /* DOMID_SELF is used in certain contexts to refer to oneself. */
  93 #define DOMID_SELF (0x7FF0U)
  94
  95 /*
  96  * DOMID_IO is used to restrict page-table updates to mapping I/O memory.
  97  * Although no Foreign Domain need be specified to map I/O pages, DOMID_IO
  98  * is useful to ensure that no mappings to the OS's own heap are accidentally
  99  * installed. (e.g., in Linux this could cause havoc as reference counts
 100  * aren't adjusted on the I/O-mapping code path).
 101  * This only makes sense in MMUEXT_SET_FOREIGNDOM, but in that context can
 102  * be specified by any calling domain.
 103  */
 104 #define DOMID_IO   (0x7FF1U)
 105
 106 /*
 107  * DOMID_XEN is used to allow privileged domains to map restricted parts of
 108  * Xen's heap space (e.g., the machine_to_phys table).
 109  * This only makes sense in MMUEXT_SET_FOREIGNDOM, and is only permitted if
 110  * the caller is privileged.
 111  */
 112 #define DOMID_XEN  (0x7FF2U)
 113
 114 /* DOMID_COW is used as the owner of sharable pages */
 115 #define DOMID_COW  (0x7FF3U)
 116
 117 /* DOMID_INVALID is used to identify pages with unknown owner. */
 118 #define DOMID_INVALID (0x7FF4U)
 119
 120 /* Idle domain. */
 121 #define DOMID_IDLE (0x7FFFU)
 122
 123 struct vcpu_info {
 124         /*
 125          * 'evtchn_upcall_pending' is written non-zero by Xen to indicate
 126          * a pending notification for a particular VCPU. It is then cleared
 127          * by the guest OS /before/ checking for pending work, thus avoiding
 128          * a set-and-check race. Note that the mask is only accessed by Xen
 129          * on the CPU that is currently hosting the VCPU. This means that the
 130          * pending and mask flags can be updated by the guest without special
 131          * synchronisation (i.e., no need for the x86 LOCK prefix).
 132          * This may seem suboptimal because if the pending flag is set by
 133          * a different CPU then an IPI may be scheduled even when the mask
 134          * is set. However, note:
 135          *  1. The task of 'interrupt holdoff' is covered by the per-event-
 136          *     channel mask bits. A 'noisy' event that is continually being
 137          *     triggered can be masked at source at this very precise
 138          *     granularity.
 139          *  2. The main purpose of the per-VCPU mask is therefore to restrict
 140          *     reentrant execution: whether for concurrency control, or to
 141          *     prevent unbounded stack usage. Whatever the purpose, we expect
 142          *     that the mask will be asserted only for short periods at a time,
 143          *     and so the likelihood of a 'spurious' IPI is suitably small.
 144          * The mask is read before making an event upcall to the guest: a
 145          * non-zero mask therefore guarantees that the VCPU will not receive
 146          * an upcall activation. The mask is cleared when the VCPU requests
 147          * to block: this avoids wakeup-waiting races.
 148          */
 149         u8 evtchn_upcall_pending;
 150         u8 evtchn_upcall_mask;
 151         xen_ulong_t evtchn_pending_sel;
 152         struct arch_vcpu_info arch;
 153         struct pvclock_vcpu_time_info time;
 154 }; /* 64 bytes (x86) */
 155
 156 /*
 157  * Xen/kernel shared data -- pointer provided in start_info.
 158  * NB. We expect that this struct is smaller than a page.
 159  */
 160 struct shared_info {
 161         struct vcpu_info vcpu_info[MAX_VIRT_CPUS];
 162
 163         /*
 164          * A domain can create "event channels" on which it can send and receive
 165          * asynchronous event notifications. There are three classes of event that
 166          * are delivered by this mechanism:
 167          *  1. Bi-directional inter- and intra-domain connections. Domains must
 168          *     arrange out-of-band to set up a connection (usually by allocating
 169          *     an unbound 'listener' port and avertising that via a storage service
 170          *     such as xenstore).
 171          *  2. Physical interrupts. A domain with suitable hardware-access
 172          *     privileges can bind an event-channel port to a physical interrupt
 173          *     source.
 174          *  3. Virtual interrupts ('events'). A domain can bind an event-channel
 175          *     port to a virtual interrupt source, such as the virtual-timer
 176          *     device or the emergency console.
 177          *
 178          * Event channels are addressed by a "port index". Each channel is
 179          * associated with two bits of information:
 180          *  1. PENDING -- notifies the domain that there is a pending notification
 181          *     to be processed. This bit is cleared by the guest.
 182          *  2. MASK -- if this bit is clear then a 0->1 transition of PENDING
 183          *     will cause an asynchronous upcall to be scheduled. This bit is only
 184          *     updated by the guest. It is read-only within Xen. If a channel
 185          *     becomes pending while the channel is masked then the 'edge' is lost
 186          *     (i.e., when the channel is unmasked, the guest must manually handle
 187          *     pending notifications as no upcall will be scheduled by Xen).
 188          *
 189          * To expedite scanning of pending notifications, any 0->1 pending
 190          * transition on an unmasked channel causes a corresponding bit in a
 191          * per-vcpu selector word to be set. Each bit in the selector covers a
 192          * 'C long' in the PENDING bitfield array.
 193          */
 194         xen_ulong_t evtchn_pending[sizeof(xen_ulong_t) * 8];
 195         xen_ulong_t evtchn_mask[sizeof(xen_ulong_t) * 8];
 196
 197         /*
 198          * Wallclock time: updated only by control software. Guests should base
 199          * their gettimeofday() syscall on this wallclock-base value.
 200          */
 201         struct pvclock_wall_clock wc;
 202
 203         struct arch_shared_info arch;
 204
 205 };
 206
 207 #else /* __ASSEMBLY__ */
 208
 209 /* In assembly code we cannot use C numeric constant suffixes. */
 210 #define mk_unsigned_long(x) x
 211
 212 #endif /* !__ASSEMBLY__ */
 213
 214 #endif /* __XEN_PUBLIC_XEN_H__ */