13a9fd824SRoger Pau Monné /****************************************************************************** 23a9fd824SRoger Pau Monné * vcpu.h 33a9fd824SRoger Pau Monné * 43a9fd824SRoger Pau Monné * VCPU initialisation, query, and hotplug. 53a9fd824SRoger Pau Monné * 63a9fd824SRoger Pau Monné * Permission is hereby granted, free of charge, to any person obtaining a copy 73a9fd824SRoger Pau Monné * of this software and associated documentation files (the "Software"), to 83a9fd824SRoger Pau Monné * deal in the Software without restriction, including without limitation the 93a9fd824SRoger Pau Monné * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 103a9fd824SRoger Pau Monné * sell copies of the Software, and to permit persons to whom the Software is 113a9fd824SRoger Pau Monné * furnished to do so, subject to the following conditions: 123a9fd824SRoger Pau Monné * 133a9fd824SRoger Pau Monné * The above copyright notice and this permission notice shall be included in 143a9fd824SRoger Pau Monné * all copies or substantial portions of the Software. 153a9fd824SRoger Pau Monné * 163a9fd824SRoger Pau Monné * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 173a9fd824SRoger Pau Monné * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 183a9fd824SRoger Pau Monné * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 193a9fd824SRoger Pau Monné * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 203a9fd824SRoger Pau Monné * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 213a9fd824SRoger Pau Monné * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 223a9fd824SRoger Pau Monné * DEALINGS IN THE SOFTWARE. 233a9fd824SRoger Pau Monné * 243a9fd824SRoger Pau Monné * Copyright (c) 2005, Keir Fraser <keir@xensource.com> 253a9fd824SRoger Pau Monné */ 263a9fd824SRoger Pau Monné 273a9fd824SRoger Pau Monné #ifndef __XEN_PUBLIC_VCPU_H__ 283a9fd824SRoger Pau Monné #define __XEN_PUBLIC_VCPU_H__ 293a9fd824SRoger Pau Monné 303a9fd824SRoger Pau Monné #include "xen.h" 313a9fd824SRoger Pau Monné 323a9fd824SRoger Pau Monné /* 333a9fd824SRoger Pau Monné * Prototype for this hypercall is: 343a9fd824SRoger Pau Monné * long vcpu_op(int cmd, unsigned int vcpuid, void *extra_args) 353a9fd824SRoger Pau Monné * @cmd == VCPUOP_??? (VCPU operation). 363a9fd824SRoger Pau Monné * @vcpuid == VCPU to operate on. 373a9fd824SRoger Pau Monné * @extra_args == Operation-specific extra arguments (NULL if none). 383a9fd824SRoger Pau Monné */ 393a9fd824SRoger Pau Monné 403a9fd824SRoger Pau Monné /* 413a9fd824SRoger Pau Monné * Initialise a VCPU. Each VCPU can be initialised only once. A 423a9fd824SRoger Pau Monné * newly-initialised VCPU will not run until it is brought up by VCPUOP_up. 433a9fd824SRoger Pau Monné * 443a9fd824SRoger Pau Monné * @extra_arg == For PV or ARM guests this is a pointer to a vcpu_guest_context 453a9fd824SRoger Pau Monné * structure containing the initial state for the VCPU. For x86 463a9fd824SRoger Pau Monné * HVM based guests this is a pointer to a vcpu_hvm_context 473a9fd824SRoger Pau Monné * structure. 483a9fd824SRoger Pau Monné */ 493a9fd824SRoger Pau Monné #define VCPUOP_initialise 0 503a9fd824SRoger Pau Monné 513a9fd824SRoger Pau Monné /* 523a9fd824SRoger Pau Monné * Bring up a VCPU. This makes the VCPU runnable. This operation will fail 533a9fd824SRoger Pau Monné * if the VCPU has not been initialised (VCPUOP_initialise). 543a9fd824SRoger Pau Monné */ 553a9fd824SRoger Pau Monné #define VCPUOP_up 1 563a9fd824SRoger Pau Monné 573a9fd824SRoger Pau Monné /* 583a9fd824SRoger Pau Monné * Bring down a VCPU (i.e., make it non-runnable). 593a9fd824SRoger Pau Monné * There are a few caveats that callers should observe: 603a9fd824SRoger Pau Monné * 1. This operation may return, and VCPU_is_up may return false, before the 613a9fd824SRoger Pau Monné * VCPU stops running (i.e., the command is asynchronous). It is a good 623a9fd824SRoger Pau Monné * idea to ensure that the VCPU has entered a non-critical loop before 633a9fd824SRoger Pau Monné * bringing it down. Alternatively, this operation is guaranteed 643a9fd824SRoger Pau Monné * synchronous if invoked by the VCPU itself. 653a9fd824SRoger Pau Monné * 2. After a VCPU is initialised, there is currently no way to drop all its 663a9fd824SRoger Pau Monné * references to domain memory. Even a VCPU that is down still holds 673a9fd824SRoger Pau Monné * memory references via its pagetable base pointer and GDT. It is good 683a9fd824SRoger Pau Monné * practise to move a VCPU onto an 'idle' or default page table, LDT and 693a9fd824SRoger Pau Monné * GDT before bringing it down. 703a9fd824SRoger Pau Monné */ 713a9fd824SRoger Pau Monné #define VCPUOP_down 2 723a9fd824SRoger Pau Monné 733a9fd824SRoger Pau Monné /* Returns 1 if the given VCPU is up. */ 743a9fd824SRoger Pau Monné #define VCPUOP_is_up 3 753a9fd824SRoger Pau Monné 763a9fd824SRoger Pau Monné /* 773a9fd824SRoger Pau Monné * Return information about the state and running time of a VCPU. 783a9fd824SRoger Pau Monné * @extra_arg == pointer to vcpu_runstate_info structure. 793a9fd824SRoger Pau Monné */ 803a9fd824SRoger Pau Monné #define VCPUOP_get_runstate_info 4 813a9fd824SRoger Pau Monné struct vcpu_runstate_info { 823a9fd824SRoger Pau Monné /* VCPU's current state (RUNSTATE_*). */ 833a9fd824SRoger Pau Monné int state; 843a9fd824SRoger Pau Monné /* When was current state entered (system time, ns)? */ 853a9fd824SRoger Pau Monné uint64_t state_entry_time; 863a9fd824SRoger Pau Monné /* 873a9fd824SRoger Pau Monné * Update indicator set in state_entry_time: 883a9fd824SRoger Pau Monné * When activated via VMASST_TYPE_runstate_update_flag, set during 893a9fd824SRoger Pau Monné * updates in guest memory mapped copy of vcpu_runstate_info. 903a9fd824SRoger Pau Monné */ 913a9fd824SRoger Pau Monné #define XEN_RUNSTATE_UPDATE (xen_mk_ullong(1) << 63) 923a9fd824SRoger Pau Monné /* 933a9fd824SRoger Pau Monné * Time spent in each RUNSTATE_* (ns). The sum of these times is 943a9fd824SRoger Pau Monné * guaranteed not to drift from system time. 953a9fd824SRoger Pau Monné */ 963a9fd824SRoger Pau Monné uint64_t time[4]; 973a9fd824SRoger Pau Monné }; 983a9fd824SRoger Pau Monné typedef struct vcpu_runstate_info vcpu_runstate_info_t; 993a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_runstate_info_t); 1003a9fd824SRoger Pau Monné 1013a9fd824SRoger Pau Monné /* VCPU is currently running on a physical CPU. */ 1023a9fd824SRoger Pau Monné #define RUNSTATE_running 0 1033a9fd824SRoger Pau Monné 1043a9fd824SRoger Pau Monné /* VCPU is runnable, but not currently scheduled on any physical CPU. */ 1053a9fd824SRoger Pau Monné #define RUNSTATE_runnable 1 1063a9fd824SRoger Pau Monné 1073a9fd824SRoger Pau Monné /* VCPU is blocked (a.k.a. idle). It is therefore not runnable. */ 1083a9fd824SRoger Pau Monné #define RUNSTATE_blocked 2 1093a9fd824SRoger Pau Monné 1103a9fd824SRoger Pau Monné /* 1113a9fd824SRoger Pau Monné * VCPU is not runnable, but it is not blocked. 1123a9fd824SRoger Pau Monné * This is a 'catch all' state for things like hotplug and pauses by the 1133a9fd824SRoger Pau Monné * system administrator (or for critical sections in the hypervisor). 1143a9fd824SRoger Pau Monné * RUNSTATE_blocked dominates this state (it is the preferred state). 1153a9fd824SRoger Pau Monné */ 1163a9fd824SRoger Pau Monné #define RUNSTATE_offline 3 1173a9fd824SRoger Pau Monné 1183a9fd824SRoger Pau Monné /* 1193a9fd824SRoger Pau Monné * Register a shared memory area from which the guest may obtain its own 1203a9fd824SRoger Pau Monné * runstate information without needing to execute a hypercall. 1213a9fd824SRoger Pau Monné * Notes: 1223a9fd824SRoger Pau Monné * 1. The registered address may be virtual or physical or guest handle, 1233a9fd824SRoger Pau Monné * depending on the platform. Virtual address or guest handle should be 1243a9fd824SRoger Pau Monné * registered on x86 systems. 1253a9fd824SRoger Pau Monné * 2. Only one shared area may be registered per VCPU. The shared area is 1263a9fd824SRoger Pau Monné * updated by the hypervisor each time the VCPU is scheduled. Thus 1273a9fd824SRoger Pau Monné * runstate.state will always be RUNSTATE_running and 1283a9fd824SRoger Pau Monné * runstate.state_entry_time will indicate the system time at which the 1293a9fd824SRoger Pau Monné * VCPU was last scheduled to run. 1303a9fd824SRoger Pau Monné * @extra_arg == pointer to vcpu_register_runstate_memory_area structure. 1313a9fd824SRoger Pau Monné */ 1323a9fd824SRoger Pau Monné #define VCPUOP_register_runstate_memory_area 5 1333a9fd824SRoger Pau Monné struct vcpu_register_runstate_memory_area { 1343a9fd824SRoger Pau Monné union { 1353a9fd824SRoger Pau Monné XEN_GUEST_HANDLE(vcpu_runstate_info_t) h; 1363a9fd824SRoger Pau Monné struct vcpu_runstate_info *v; 1373a9fd824SRoger Pau Monné uint64_t p; 1383a9fd824SRoger Pau Monné } addr; 1393a9fd824SRoger Pau Monné }; 1403a9fd824SRoger Pau Monné typedef struct vcpu_register_runstate_memory_area vcpu_register_runstate_memory_area_t; 1413a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_register_runstate_memory_area_t); 1423a9fd824SRoger Pau Monné 1433a9fd824SRoger Pau Monné /* 1443a9fd824SRoger Pau Monné * Set or stop a VCPU's periodic timer. Every VCPU has one periodic timer 1453a9fd824SRoger Pau Monné * which can be set via these commands. Periods smaller than one millisecond 1463a9fd824SRoger Pau Monné * may not be supported. 1473a9fd824SRoger Pau Monné */ 1483a9fd824SRoger Pau Monné #define VCPUOP_set_periodic_timer 6 /* arg == vcpu_set_periodic_timer_t */ 1493a9fd824SRoger Pau Monné #define VCPUOP_stop_periodic_timer 7 /* arg == NULL */ 1503a9fd824SRoger Pau Monné struct vcpu_set_periodic_timer { 1513a9fd824SRoger Pau Monné uint64_t period_ns; 1523a9fd824SRoger Pau Monné }; 1533a9fd824SRoger Pau Monné typedef struct vcpu_set_periodic_timer vcpu_set_periodic_timer_t; 1543a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_set_periodic_timer_t); 1553a9fd824SRoger Pau Monné 1563a9fd824SRoger Pau Monné /* 1573a9fd824SRoger Pau Monné * Set or stop a VCPU's single-shot timer. Every VCPU has one single-shot 1583a9fd824SRoger Pau Monné * timer which can be set via these commands. 1593a9fd824SRoger Pau Monné */ 1603a9fd824SRoger Pau Monné #define VCPUOP_set_singleshot_timer 8 /* arg == vcpu_set_singleshot_timer_t */ 1613a9fd824SRoger Pau Monné #define VCPUOP_stop_singleshot_timer 9 /* arg == NULL */ 1623a9fd824SRoger Pau Monné struct vcpu_set_singleshot_timer { 1633a9fd824SRoger Pau Monné uint64_t timeout_abs_ns; /* Absolute system time value in nanoseconds. */ 1643a9fd824SRoger Pau Monné uint32_t flags; /* VCPU_SSHOTTMR_??? */ 1653a9fd824SRoger Pau Monné }; 1663a9fd824SRoger Pau Monné typedef struct vcpu_set_singleshot_timer vcpu_set_singleshot_timer_t; 1673a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_set_singleshot_timer_t); 1683a9fd824SRoger Pau Monné 1693a9fd824SRoger Pau Monné /* Flags to VCPUOP_set_singleshot_timer. */ 1703a9fd824SRoger Pau Monné /* Require the timeout to be in the future (return -ETIME if it's passed). */ 1713a9fd824SRoger Pau Monné #define _VCPU_SSHOTTMR_future (0) 1723a9fd824SRoger Pau Monné #define VCPU_SSHOTTMR_future (1U << _VCPU_SSHOTTMR_future) 1733a9fd824SRoger Pau Monné 1743a9fd824SRoger Pau Monné /* 1753a9fd824SRoger Pau Monné * Register a memory location in the guest address space for the 1763a9fd824SRoger Pau Monné * vcpu_info structure. This allows the guest to place the vcpu_info 1773a9fd824SRoger Pau Monné * structure in a convenient place, such as in a per-cpu data area. 1783a9fd824SRoger Pau Monné * The pointer need not be page aligned, but the structure must not 1793a9fd824SRoger Pau Monné * cross a page boundary. 1803a9fd824SRoger Pau Monné * 1813a9fd824SRoger Pau Monné * This may be called only once per vcpu. 1823a9fd824SRoger Pau Monné */ 1833a9fd824SRoger Pau Monné #define VCPUOP_register_vcpu_info 10 /* arg == vcpu_register_vcpu_info_t */ 1843a9fd824SRoger Pau Monné struct vcpu_register_vcpu_info { 1853a9fd824SRoger Pau Monné uint64_t mfn; /* mfn of page to place vcpu_info */ 1863a9fd824SRoger Pau Monné uint32_t offset; /* offset within page */ 1873a9fd824SRoger Pau Monné uint32_t rsvd; /* unused */ 1883a9fd824SRoger Pau Monné }; 1893a9fd824SRoger Pau Monné typedef struct vcpu_register_vcpu_info vcpu_register_vcpu_info_t; 1903a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_register_vcpu_info_t); 1913a9fd824SRoger Pau Monné 1923a9fd824SRoger Pau Monné /* Send an NMI to the specified VCPU. @extra_arg == NULL. */ 1933a9fd824SRoger Pau Monné #define VCPUOP_send_nmi 11 1943a9fd824SRoger Pau Monné 1953a9fd824SRoger Pau Monné /* 1963a9fd824SRoger Pau Monné * Get the physical ID information for a pinned vcpu's underlying physical 1973a9fd824SRoger Pau Monné * processor. The physical ID informmation is architecture-specific. 1983a9fd824SRoger Pau Monné * On x86: id[31:0]=apic_id, id[63:32]=acpi_id. 1993a9fd824SRoger Pau Monné * This command returns -EINVAL if it is not a valid operation for this VCPU. 2003a9fd824SRoger Pau Monné */ 2013a9fd824SRoger Pau Monné #define VCPUOP_get_physid 12 /* arg == vcpu_get_physid_t */ 2023a9fd824SRoger Pau Monné struct vcpu_get_physid { 2033a9fd824SRoger Pau Monné uint64_t phys_id; 2043a9fd824SRoger Pau Monné }; 2053a9fd824SRoger Pau Monné typedef struct vcpu_get_physid vcpu_get_physid_t; 2063a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_get_physid_t); 2073a9fd824SRoger Pau Monné #define xen_vcpu_physid_to_x86_apicid(physid) ((uint32_t)(physid)) 2083a9fd824SRoger Pau Monné #define xen_vcpu_physid_to_x86_acpiid(physid) ((uint32_t)((physid) >> 32)) 2093a9fd824SRoger Pau Monné 2103a9fd824SRoger Pau Monné /* 2113a9fd824SRoger Pau Monné * Register a memory location to get a secondary copy of the vcpu time 2123a9fd824SRoger Pau Monné * parameters. The master copy still exists as part of the vcpu shared 2133a9fd824SRoger Pau Monné * memory area, and this secondary copy is updated whenever the master copy 2143a9fd824SRoger Pau Monné * is updated (and using the same versioning scheme for synchronisation). 2153a9fd824SRoger Pau Monné * 2163a9fd824SRoger Pau Monné * The intent is that this copy may be mapped (RO) into userspace so 2173a9fd824SRoger Pau Monné * that usermode can compute system time using the time info and the 2183a9fd824SRoger Pau Monné * tsc. Usermode will see an array of vcpu_time_info structures, one 2193a9fd824SRoger Pau Monné * for each vcpu, and choose the right one by an existing mechanism 2203a9fd824SRoger Pau Monné * which allows it to get the current vcpu number (such as via a 2213a9fd824SRoger Pau Monné * segment limit). It can then apply the normal algorithm to compute 2223a9fd824SRoger Pau Monné * system time from the tsc. 2233a9fd824SRoger Pau Monné * 2243a9fd824SRoger Pau Monné * @extra_arg == pointer to vcpu_register_time_info_memory_area structure. 2253a9fd824SRoger Pau Monné */ 2263a9fd824SRoger Pau Monné #define VCPUOP_register_vcpu_time_memory_area 13 2273a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_time_info_t); 2283a9fd824SRoger Pau Monné struct vcpu_register_time_memory_area { 2293a9fd824SRoger Pau Monné union { 2303a9fd824SRoger Pau Monné XEN_GUEST_HANDLE(vcpu_time_info_t) h; 2313a9fd824SRoger Pau Monné struct vcpu_time_info *v; 2323a9fd824SRoger Pau Monné uint64_t p; 2333a9fd824SRoger Pau Monné } addr; 2343a9fd824SRoger Pau Monné }; 2353a9fd824SRoger Pau Monné typedef struct vcpu_register_time_memory_area vcpu_register_time_memory_area_t; 2363a9fd824SRoger Pau Monné DEFINE_XEN_GUEST_HANDLE(vcpu_register_time_memory_area_t); 2373a9fd824SRoger Pau Monné 2383a9fd824SRoger Pau Monné #endif /* __XEN_PUBLIC_VCPU_H__ */ 2393a9fd824SRoger Pau Monné 2403a9fd824SRoger Pau Monné /* 2413a9fd824SRoger Pau Monné * Local variables: 2423a9fd824SRoger Pau Monné * mode: C 2433a9fd824SRoger Pau Monné * c-file-style: "BSD" 2443a9fd824SRoger Pau Monné * c-basic-offset: 4 2453a9fd824SRoger Pau Monné * tab-width: 4 2463a9fd824SRoger Pau Monné * indent-tabs-mode: nil 2473a9fd824SRoger Pau Monné * End: 2483a9fd824SRoger Pau Monné */ 249