1181624Skmacy/****************************************************************************** 2181624Skmacy * vcpu.h 3181624Skmacy * 4181624Skmacy * VCPU initialisation, query, and hotplug. 5181624Skmacy * 6181624Skmacy * Permission is hereby granted, free of charge, to any person obtaining a copy 7181624Skmacy * of this software and associated documentation files (the "Software"), to 8181624Skmacy * deal in the Software without restriction, including without limitation the 9181624Skmacy * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10181624Skmacy * sell copies of the Software, and to permit persons to whom the Software is 11181624Skmacy * furnished to do so, subject to the following conditions: 12181624Skmacy * 13181624Skmacy * The above copyright notice and this permission notice shall be included in 14181624Skmacy * all copies or substantial portions of the Software. 15181624Skmacy * 16181624Skmacy * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17181624Skmacy * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18181624Skmacy * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19181624Skmacy * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20181624Skmacy * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21181624Skmacy * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 22181624Skmacy * DEALINGS IN THE SOFTWARE. 23181624Skmacy * 24181624Skmacy * Copyright (c) 2005, Keir Fraser <keir@xensource.com> 25181624Skmacy */ 26181624Skmacy 27181624Skmacy#ifndef __XEN_PUBLIC_VCPU_H__ 28181624Skmacy#define __XEN_PUBLIC_VCPU_H__ 29181624Skmacy 30251767Sgibbs#include "xen.h" 31251767Sgibbs 32181624Skmacy/* 33181624Skmacy * Prototype for this hypercall is: 34181624Skmacy * int vcpu_op(int cmd, int vcpuid, void *extra_args) 35181624Skmacy * @cmd == VCPUOP_??? (VCPU operation). 36181624Skmacy * @vcpuid == VCPU to operate on. 37181624Skmacy * @extra_args == Operation-specific extra arguments (NULL if none). 38181624Skmacy */ 39181624Skmacy 40181624Skmacy/* 41181624Skmacy * Initialise a VCPU. Each VCPU can be initialised only once. A 42181624Skmacy * newly-initialised VCPU will not run until it is brought up by VCPUOP_up. 43181624Skmacy * 44181624Skmacy * @extra_arg == pointer to vcpu_guest_context structure containing initial 45181624Skmacy * state for the VCPU. 46181624Skmacy */ 47181624Skmacy#define VCPUOP_initialise 0 48181624Skmacy 49181624Skmacy/* 50181624Skmacy * Bring up a VCPU. This makes the VCPU runnable. This operation will fail 51181624Skmacy * if the VCPU has not been initialised (VCPUOP_initialise). 52181624Skmacy */ 53181624Skmacy#define VCPUOP_up 1 54181624Skmacy 55181624Skmacy/* 56181624Skmacy * Bring down a VCPU (i.e., make it non-runnable). 57181624Skmacy * There are a few caveats that callers should observe: 58181624Skmacy * 1. This operation may return, and VCPU_is_up may return false, before the 59181624Skmacy * VCPU stops running (i.e., the command is asynchronous). It is a good 60181624Skmacy * idea to ensure that the VCPU has entered a non-critical loop before 61181624Skmacy * bringing it down. Alternatively, this operation is guaranteed 62181624Skmacy * synchronous if invoked by the VCPU itself. 63181624Skmacy * 2. After a VCPU is initialised, there is currently no way to drop all its 64181624Skmacy * references to domain memory. Even a VCPU that is down still holds 65181624Skmacy * memory references via its pagetable base pointer and GDT. It is good 66181624Skmacy * practise to move a VCPU onto an 'idle' or default page table, LDT and 67181624Skmacy * GDT before bringing it down. 68181624Skmacy */ 69181624Skmacy#define VCPUOP_down 2 70181624Skmacy 71181624Skmacy/* Returns 1 if the given VCPU is up. */ 72181624Skmacy#define VCPUOP_is_up 3 73181624Skmacy 74181624Skmacy/* 75181624Skmacy * Return information about the state and running time of a VCPU. 76181624Skmacy * @extra_arg == pointer to vcpu_runstate_info structure. 77181624Skmacy */ 78181624Skmacy#define VCPUOP_get_runstate_info 4 79181624Skmacystruct vcpu_runstate_info { 80181624Skmacy /* VCPU's current state (RUNSTATE_*). */ 81181624Skmacy int state; 82181624Skmacy /* When was current state entered (system time, ns)? */ 83181624Skmacy uint64_t state_entry_time; 84181624Skmacy /* 85181624Skmacy * Time spent in each RUNSTATE_* (ns). The sum of these times is 86181624Skmacy * guaranteed not to drift from system time. 87181624Skmacy */ 88181624Skmacy uint64_t time[4]; 89181624Skmacy}; 90181624Skmacytypedef struct vcpu_runstate_info vcpu_runstate_info_t; 91181624SkmacyDEFINE_XEN_GUEST_HANDLE(vcpu_runstate_info_t); 92181624Skmacy 93181624Skmacy/* VCPU is currently running on a physical CPU. */ 94181624Skmacy#define RUNSTATE_running 0 95181624Skmacy 96181624Skmacy/* VCPU is runnable, but not currently scheduled on any physical CPU. */ 97181624Skmacy#define RUNSTATE_runnable 1 98181624Skmacy 99181624Skmacy/* VCPU is blocked (a.k.a. idle). It is therefore not runnable. */ 100181624Skmacy#define RUNSTATE_blocked 2 101181624Skmacy 102181624Skmacy/* 103181624Skmacy * VCPU is not runnable, but it is not blocked. 104181624Skmacy * This is a 'catch all' state for things like hotplug and pauses by the 105181624Skmacy * system administrator (or for critical sections in the hypervisor). 106181624Skmacy * RUNSTATE_blocked dominates this state (it is the preferred state). 107181624Skmacy */ 108181624Skmacy#define RUNSTATE_offline 3 109181624Skmacy 110181624Skmacy/* 111181624Skmacy * Register a shared memory area from which the guest may obtain its own 112181624Skmacy * runstate information without needing to execute a hypercall. 113181624Skmacy * Notes: 114181624Skmacy * 1. The registered address may be virtual or physical or guest handle, 115181624Skmacy * depending on the platform. Virtual address or guest handle should be 116181624Skmacy * registered on x86 systems. 117181624Skmacy * 2. Only one shared area may be registered per VCPU. The shared area is 118181624Skmacy * updated by the hypervisor each time the VCPU is scheduled. Thus 119181624Skmacy * runstate.state will always be RUNSTATE_running and 120181624Skmacy * runstate.state_entry_time will indicate the system time at which the 121181624Skmacy * VCPU was last scheduled to run. 122181624Skmacy * @extra_arg == pointer to vcpu_register_runstate_memory_area structure. 123181624Skmacy */ 124181624Skmacy#define VCPUOP_register_runstate_memory_area 5 125181624Skmacystruct vcpu_register_runstate_memory_area { 126181624Skmacy union { 127181624Skmacy XEN_GUEST_HANDLE(vcpu_runstate_info_t) h; 128181624Skmacy struct vcpu_runstate_info *v; 129181624Skmacy uint64_t p; 130181624Skmacy } addr; 131181624Skmacy}; 132181624Skmacytypedef struct vcpu_register_runstate_memory_area vcpu_register_runstate_memory_area_t; 133181624SkmacyDEFINE_XEN_GUEST_HANDLE(vcpu_register_runstate_memory_area_t); 134181624Skmacy 135181624Skmacy/* 136181624Skmacy * Set or stop a VCPU's periodic timer. Every VCPU has one periodic timer 137181624Skmacy * which can be set via these commands. Periods smaller than one millisecond 138181624Skmacy * may not be supported. 139181624Skmacy */ 140181624Skmacy#define VCPUOP_set_periodic_timer 6 /* arg == vcpu_set_periodic_timer_t */ 141181624Skmacy#define VCPUOP_stop_periodic_timer 7 /* arg == NULL */ 142181624Skmacystruct vcpu_set_periodic_timer { 143181624Skmacy uint64_t period_ns; 144181624Skmacy}; 145181624Skmacytypedef struct vcpu_set_periodic_timer vcpu_set_periodic_timer_t; 146181624SkmacyDEFINE_XEN_GUEST_HANDLE(vcpu_set_periodic_timer_t); 147181624Skmacy 148181624Skmacy/* 149181624Skmacy * Set or stop a VCPU's single-shot timer. Every VCPU has one single-shot 150181624Skmacy * timer which can be set via these commands. 151181624Skmacy */ 152181624Skmacy#define VCPUOP_set_singleshot_timer 8 /* arg == vcpu_set_singleshot_timer_t */ 153181624Skmacy#define VCPUOP_stop_singleshot_timer 9 /* arg == NULL */ 154181624Skmacystruct vcpu_set_singleshot_timer { 155181624Skmacy uint64_t timeout_abs_ns; /* Absolute system time value in nanoseconds. */ 156181624Skmacy uint32_t flags; /* VCPU_SSHOTTMR_??? */ 157181624Skmacy}; 158181624Skmacytypedef struct vcpu_set_singleshot_timer vcpu_set_singleshot_timer_t; 159181624SkmacyDEFINE_XEN_GUEST_HANDLE(vcpu_set_singleshot_timer_t); 160181624Skmacy 161181624Skmacy/* Flags to VCPUOP_set_singleshot_timer. */ 162181624Skmacy /* Require the timeout to be in the future (return -ETIME if it's passed). */ 163181624Skmacy#define _VCPU_SSHOTTMR_future (0) 164181624Skmacy#define VCPU_SSHOTTMR_future (1U << _VCPU_SSHOTTMR_future) 165181624Skmacy 166181624Skmacy/* 167181624Skmacy * Register a memory location in the guest address space for the 168181624Skmacy * vcpu_info structure. This allows the guest to place the vcpu_info 169181624Skmacy * structure in a convenient place, such as in a per-cpu data area. 170181624Skmacy * The pointer need not be page aligned, but the structure must not 171181624Skmacy * cross a page boundary. 172181624Skmacy * 173181624Skmacy * This may be called only once per vcpu. 174181624Skmacy */ 175183340Skmacy#define VCPUOP_register_vcpu_info 10 /* arg == vcpu_register_vcpu_info_t */ 176181624Skmacystruct vcpu_register_vcpu_info { 177181624Skmacy uint64_t mfn; /* mfn of page to place vcpu_info */ 178181624Skmacy uint32_t offset; /* offset within page */ 179181624Skmacy uint32_t rsvd; /* unused */ 180181624Skmacy}; 181181624Skmacytypedef struct vcpu_register_vcpu_info vcpu_register_vcpu_info_t; 182181624SkmacyDEFINE_XEN_GUEST_HANDLE(vcpu_register_vcpu_info_t); 183181624Skmacy 184183340Skmacy/* Send an NMI to the specified VCPU. @extra_arg == NULL. */ 185183340Skmacy#define VCPUOP_send_nmi 11 186183340Skmacy 187183340Skmacy/* 188183340Skmacy * Get the physical ID information for a pinned vcpu's underlying physical 189183340Skmacy * processor. The physical ID informmation is architecture-specific. 190251767Sgibbs * On x86: id[31:0]=apic_id, id[63:32]=acpi_id. 191183340Skmacy * This command returns -EINVAL if it is not a valid operation for this VCPU. 192183340Skmacy */ 193183340Skmacy#define VCPUOP_get_physid 12 /* arg == vcpu_get_physid_t */ 194183340Skmacystruct vcpu_get_physid { 195183340Skmacy uint64_t phys_id; 196183340Skmacy}; 197183340Skmacytypedef struct vcpu_get_physid vcpu_get_physid_t; 198183340SkmacyDEFINE_XEN_GUEST_HANDLE(vcpu_get_physid_t); 199251767Sgibbs#define xen_vcpu_physid_to_x86_apicid(physid) ((uint32_t)(physid)) 200251767Sgibbs#define xen_vcpu_physid_to_x86_acpiid(physid) ((uint32_t)((physid) >> 32)) 201183340Skmacy 202251767Sgibbs/* 203251767Sgibbs * Register a memory location to get a secondary copy of the vcpu time 204251767Sgibbs * parameters. The master copy still exists as part of the vcpu shared 205251767Sgibbs * memory area, and this secondary copy is updated whenever the master copy 206251767Sgibbs * is updated (and using the same versioning scheme for synchronisation). 207251767Sgibbs * 208251767Sgibbs * The intent is that this copy may be mapped (RO) into userspace so 209251767Sgibbs * that usermode can compute system time using the time info and the 210251767Sgibbs * tsc. Usermode will see an array of vcpu_time_info structures, one 211251767Sgibbs * for each vcpu, and choose the right one by an existing mechanism 212251767Sgibbs * which allows it to get the current vcpu number (such as via a 213251767Sgibbs * segment limit). It can then apply the normal algorithm to compute 214251767Sgibbs * system time from the tsc. 215251767Sgibbs * 216251767Sgibbs * @extra_arg == pointer to vcpu_register_time_info_memory_area structure. 217251767Sgibbs */ 218251767Sgibbs#define VCPUOP_register_vcpu_time_memory_area 13 219251767SgibbsDEFINE_XEN_GUEST_HANDLE(vcpu_time_info_t); 220251767Sgibbsstruct vcpu_register_time_memory_area { 221251767Sgibbs union { 222251767Sgibbs XEN_GUEST_HANDLE(vcpu_time_info_t) h; 223251767Sgibbs struct vcpu_time_info *v; 224251767Sgibbs uint64_t p; 225251767Sgibbs } addr; 226251767Sgibbs}; 227251767Sgibbstypedef struct vcpu_register_time_memory_area vcpu_register_time_memory_area_t; 228251767SgibbsDEFINE_XEN_GUEST_HANDLE(vcpu_register_time_memory_area_t); 229251767Sgibbs 230181624Skmacy#endif /* __XEN_PUBLIC_VCPU_H__ */ 231181624Skmacy 232181624Skmacy/* 233181624Skmacy * Local variables: 234181624Skmacy * mode: C 235181624Skmacy * c-set-style: "BSD" 236181624Skmacy * c-basic-offset: 4 237181624Skmacy * tab-width: 4 238181624Skmacy * indent-tabs-mode: nil 239181624Skmacy * End: 240181624Skmacy */ 241