Commit | Line | Data |
---|---|---|
a42089dd JF |
1 | /****************************************************************************** |
2 | * vcpu.h | |
3 | * | |
4 | * VCPU initialisation, query, and hotplug. | |
5 | * | |
6 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
7 | * of this software and associated documentation files (the "Software"), to | |
8 | * deal in the Software without restriction, including without limitation the | |
9 | * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or | |
10 | * sell copies of the Software, and to permit persons to whom the Software is | |
11 | * furnished to do so, subject to the following conditions: | |
12 | * | |
13 | * The above copyright notice and this permission notice shall be included in | |
14 | * all copies or substantial portions of the Software. | |
15 | * | |
16 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
17 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
18 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
19 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
20 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING | |
21 | * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER | |
22 | * DEALINGS IN THE SOFTWARE. | |
23 | * | |
24 | * Copyright (c) 2005, Keir Fraser <keir@xensource.com> | |
25 | */ | |
26 | ||
27 | #ifndef __XEN_PUBLIC_VCPU_H__ | |
28 | #define __XEN_PUBLIC_VCPU_H__ | |
29 | ||
30 | /* | |
31 | * Prototype for this hypercall is: | |
32 | * int vcpu_op(int cmd, int vcpuid, void *extra_args) | |
33 | * @cmd == VCPUOP_??? (VCPU operation). | |
34 | * @vcpuid == VCPU to operate on. | |
35 | * @extra_args == Operation-specific extra arguments (NULL if none). | |
36 | */ | |
37 | ||
38 | /* | |
39 | * Initialise a VCPU. Each VCPU can be initialised only once. A | |
40 | * newly-initialised VCPU will not run until it is brought up by VCPUOP_up. | |
41 | * | |
42 | * @extra_arg == pointer to vcpu_guest_context structure containing initial | |
43 | * state for the VCPU. | |
44 | */ | |
45 | #define VCPUOP_initialise 0 | |
46 | ||
47 | /* | |
48 | * Bring up a VCPU. This makes the VCPU runnable. This operation will fail | |
49 | * if the VCPU has not been initialised (VCPUOP_initialise). | |
50 | */ | |
51 | #define VCPUOP_up 1 | |
52 | ||
53 | /* | |
54 | * Bring down a VCPU (i.e., make it non-runnable). | |
55 | * There are a few caveats that callers should observe: | |
56 | * 1. This operation may return, and VCPU_is_up may return false, before the | |
57 | * VCPU stops running (i.e., the command is asynchronous). It is a good | |
58 | * idea to ensure that the VCPU has entered a non-critical loop before | |
59 | * bringing it down. Alternatively, this operation is guaranteed | |
60 | * synchronous if invoked by the VCPU itself. | |
61 | * 2. After a VCPU is initialised, there is currently no way to drop all its | |
62 | * references to domain memory. Even a VCPU that is down still holds | |
63 | * memory references via its pagetable base pointer and GDT. It is good | |
64 | * practise to move a VCPU onto an 'idle' or default page table, LDT and | |
65 | * GDT before bringing it down. | |
66 | */ | |
67 | #define VCPUOP_down 2 | |
68 | ||
69 | /* Returns 1 if the given VCPU is up. */ | |
70 | #define VCPUOP_is_up 3 | |
71 | ||
72 | /* | |
73 | * Return information about the state and running time of a VCPU. | |
74 | * @extra_arg == pointer to vcpu_runstate_info structure. | |
75 | */ | |
76 | #define VCPUOP_get_runstate_info 4 | |
77 | struct vcpu_runstate_info { | |
78 | /* VCPU's current state (RUNSTATE_*). */ | |
79 | int state; | |
80 | /* When was current state entered (system time, ns)? */ | |
81 | uint64_t state_entry_time; | |
82 | /* | |
83 | * Time spent in each RUNSTATE_* (ns). The sum of these times is | |
84 | * guaranteed not to drift from system time. | |
85 | */ | |
86 | uint64_t time[4]; | |
87 | }; | |
27244269 | 88 | DEFINE_GUEST_HANDLE_STRUCT(vcpu_runstate_info); |
a42089dd JF |
89 | |
90 | /* VCPU is currently running on a physical CPU. */ | |
91 | #define RUNSTATE_running 0 | |
92 | ||
93 | /* VCPU is runnable, but not currently scheduled on any physical CPU. */ | |
94 | #define RUNSTATE_runnable 1 | |
95 | ||
96 | /* VCPU is blocked (a.k.a. idle). It is therefore not runnable. */ | |
97 | #define RUNSTATE_blocked 2 | |
98 | ||
99 | /* | |
100 | * VCPU is not runnable, but it is not blocked. | |
101 | * This is a 'catch all' state for things like hotplug and pauses by the | |
102 | * system administrator (or for critical sections in the hypervisor). | |
103 | * RUNSTATE_blocked dominates this state (it is the preferred state). | |
104 | */ | |
105 | #define RUNSTATE_offline 3 | |
106 | ||
107 | /* | |
108 | * Register a shared memory area from which the guest may obtain its own | |
109 | * runstate information without needing to execute a hypercall. | |
110 | * Notes: | |
111 | * 1. The registered address may be virtual or physical, depending on the | |
112 | * platform. The virtual address should be registered on x86 systems. | |
113 | * 2. Only one shared area may be registered per VCPU. The shared area is | |
114 | * updated by the hypervisor each time the VCPU is scheduled. Thus | |
115 | * runstate.state will always be RUNSTATE_running and | |
116 | * runstate.state_entry_time will indicate the system time at which the | |
117 | * VCPU was last scheduled to run. | |
118 | * @extra_arg == pointer to vcpu_register_runstate_memory_area structure. | |
119 | */ | |
120 | #define VCPUOP_register_runstate_memory_area 5 | |
121 | struct vcpu_register_runstate_memory_area { | |
122 | union { | |
27244269 | 123 | GUEST_HANDLE(vcpu_runstate_info) h; |
a42089dd JF |
124 | struct vcpu_runstate_info *v; |
125 | uint64_t p; | |
126 | } addr; | |
127 | }; | |
128 | ||
129 | /* | |
130 | * Set or stop a VCPU's periodic timer. Every VCPU has one periodic timer | |
131 | * which can be set via these commands. Periods smaller than one millisecond | |
132 | * may not be supported. | |
133 | */ | |
134 | #define VCPUOP_set_periodic_timer 6 /* arg == vcpu_set_periodic_timer_t */ | |
135 | #define VCPUOP_stop_periodic_timer 7 /* arg == NULL */ | |
136 | struct vcpu_set_periodic_timer { | |
137 | uint64_t period_ns; | |
138 | }; | |
27244269 | 139 | DEFINE_GUEST_HANDLE_STRUCT(vcpu_set_periodic_timer); |
a42089dd JF |
140 | |
141 | /* | |
142 | * Set or stop a VCPU's single-shot timer. Every VCPU has one single-shot | |
143 | * timer which can be set via these commands. | |
144 | */ | |
145 | #define VCPUOP_set_singleshot_timer 8 /* arg == vcpu_set_singleshot_timer_t */ | |
146 | #define VCPUOP_stop_singleshot_timer 9 /* arg == NULL */ | |
147 | struct vcpu_set_singleshot_timer { | |
148 | uint64_t timeout_abs_ns; | |
149 | uint32_t flags; /* VCPU_SSHOTTMR_??? */ | |
150 | }; | |
27244269 | 151 | DEFINE_GUEST_HANDLE_STRUCT(vcpu_set_singleshot_timer); |
a42089dd JF |
152 | |
153 | /* Flags to VCPUOP_set_singleshot_timer. */ | |
154 | /* Require the timeout to be in the future (return -ETIME if it's passed). */ | |
155 | #define _VCPU_SSHOTTMR_future (0) | |
156 | #define VCPU_SSHOTTMR_future (1U << _VCPU_SSHOTTMR_future) | |
157 | ||
60223a32 JF |
158 | /* |
159 | * Register a memory location in the guest address space for the | |
160 | * vcpu_info structure. This allows the guest to place the vcpu_info | |
161 | * structure in a convenient place, such as in a per-cpu data area. | |
162 | * The pointer need not be page aligned, but the structure must not | |
163 | * cross a page boundary. | |
164 | */ | |
165 | #define VCPUOP_register_vcpu_info 10 /* arg == struct vcpu_info */ | |
166 | struct vcpu_register_vcpu_info { | |
e3d26976 JF |
167 | uint64_t mfn; /* mfn of page to place vcpu_info */ |
168 | uint32_t offset; /* offset within page */ | |
169 | uint32_t rsvd; /* unused */ | |
60223a32 | 170 | }; |
27244269 | 171 | DEFINE_GUEST_HANDLE_STRUCT(vcpu_register_vcpu_info); |
60223a32 | 172 | |
a42089dd | 173 | #endif /* __XEN_PUBLIC_VCPU_H__ */ |