1 /******************************************************************************
2 * sched.h
3 *
4 * Scheduler state interactions
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_SCHED_H__
28 #define __XEN_PUBLIC_SCHED_H__
29
30 #include <xen/interface/event_channel.h>
31
32 /*
33 * Guest Scheduler Operations
34 *
35 * The SCHEDOP interface provides mechanisms for a guest to interact
36 * with the scheduler, including yield, blocking and shutting itself
37 * down.
38 */
39
40 /*
41 * The prototype for this hypercall is:
42 * long HYPERVISOR_sched_op(enum sched_op cmd, void *arg, ...)
43 *
44 * @cmd == SCHEDOP_??? (scheduler operation).
45 * @arg == Operation-specific extra argument(s), as described below.
46 * ... == Additional Operation-specific extra arguments, described below.
47 *
48 * Versions of Xen prior to 3.0.2 provided only the following legacy version
49 * of this hypercall, supporting only the commands yield, block and shutdown:
50 * long sched_op(int cmd, unsigned long arg)
51 * @cmd == SCHEDOP_??? (scheduler operation).
52 * @arg == 0 (SCHEDOP_yield and SCHEDOP_block)
53 * == SHUTDOWN_* code (SCHEDOP_shutdown)
54 *
55 * This legacy version is available to new guests as:
56 * long HYPERVISOR_sched_op_compat(enum sched_op cmd, unsigned long arg)
57 */
58
59 /*
60 * Voluntarily yield the CPU.
61 * @arg == NULL.
62 */
63 #define SCHEDOP_yield 0
64
65 /*
66 * Block execution of this VCPU until an event is received for processing.
67 * If called with event upcalls masked, this operation will atomically
68 * reenable event delivery and check for pending events before blocking the
69 * VCPU. This avoids a "wakeup waiting" race.
70 * @arg == NULL.
71 */
72 #define SCHEDOP_block 1
73
74 /*
75 * Halt execution of this domain (all VCPUs) and notify the system controller.
76 * @arg == pointer to sched_shutdown structure.
77 *
78 * If the sched_shutdown_t reason is SHUTDOWN_suspend then
79 * x86 PV guests must also set RDX (EDX for 32-bit guests) to the MFN
80 * of the guest's start info page. RDX/EDX is the third hypercall
81 * argument.
82 *
83 * In addition, which reason is SHUTDOWN_suspend this hypercall
84 * returns 1 if suspend was cancelled or the domain was merely
85 * checkpointed, and 0 if it is resuming in a new domain.
86 */
87 #define SCHEDOP_shutdown 2
88
89 /*
90 * Poll a set of event-channel ports. Return when one or more are pending. An
91 * optional timeout may be specified.
92 * @arg == pointer to sched_poll structure.
93 */
94 #define SCHEDOP_poll 3
95
96 /*
97 * Declare a shutdown for another domain. The main use of this function is
98 * in interpreting shutdown requests and reasons for fully-virtualized
99 * domains. A para-virtualized domain may use SCHEDOP_shutdown directly.
100 * @arg == pointer to sched_remote_shutdown structure.
101 */
102 #define SCHEDOP_remote_shutdown 4
103
104 /*
105 * Latch a shutdown code, so that when the domain later shuts down it
106 * reports this code to the control tools.
107 * @arg == sched_shutdown, as for SCHEDOP_shutdown.
108 */
109 #define SCHEDOP_shutdown_code 5
110
111 /*
112 * Setup, poke and destroy a domain watchdog timer.
113 * @arg == pointer to sched_watchdog structure.
114 * With id == 0, setup a domain watchdog timer to cause domain shutdown
115 * after timeout, returns watchdog id.
116 * With id != 0 and timeout == 0, destroy domain watchdog timer.
117 * With id != 0 and timeout != 0, poke watchdog timer and set new timeout.
118 */
119 #define SCHEDOP_watchdog 6
120
121 /*
122 * Override the current vcpu affinity by pinning it to one physical cpu or
123 * undo this override restoring the previous affinity.
124 * @arg == pointer to sched_pin_override structure.
125 *
126 * A negative pcpu value will undo a previous pin override and restore the
127 * previous cpu affinity.
128 * This call is allowed for the hardware domain only and requires the cpu
129 * to be part of the domain's cpupool.
130 */
131 #define SCHEDOP_pin_override 7
132
133 struct sched_shutdown {
134 unsigned int reason; /* SHUTDOWN_* => shutdown reason */
135 };
136 DEFINE_GUEST_HANDLE_STRUCT(sched_shutdown);
137
138 struct sched_poll {
139 GUEST_HANDLE(evtchn_port_t) ports;
140 unsigned int nr_ports;
141 uint64_t timeout;
142 };
143 DEFINE_GUEST_HANDLE_STRUCT(sched_poll);
144
145 struct sched_remote_shutdown {
146 domid_t domain_id; /* Remote domain ID */
147 unsigned int reason; /* SHUTDOWN_* => shutdown reason */
148 };
149 DEFINE_GUEST_HANDLE_STRUCT(sched_remote_shutdown);
150
151 struct sched_watchdog {
152 uint32_t id; /* watchdog ID */
153 uint32_t timeout; /* timeout */
154 };
155 DEFINE_GUEST_HANDLE_STRUCT(sched_watchdog);
156
157 struct sched_pin_override {
158 int32_t pcpu;
159 };
160 DEFINE_GUEST_HANDLE_STRUCT(sched_pin_override);
161
162 /*
163 * Reason codes for SCHEDOP_shutdown. These may be interpreted by control
164 * software to determine the appropriate action. For the most part, Xen does
165 * not care about the shutdown code.
166 */
167 #define SHUTDOWN_poweroff 0 /* Domain exited normally. Clean up and kill. */
168 #define SHUTDOWN_reboot 1 /* Clean up, kill, and then restart. */
169 #define SHUTDOWN_suspend 2 /* Clean up, save suspend info, kill. */
170 #define SHUTDOWN_crash 3 /* Tell controller we've crashed. */
171 #define SHUTDOWN_watchdog 4 /* Restart because watchdog time expired. */
172
173 /*
174 * Domain asked to perform 'soft reset' for it. The expected behavior is to
175 * reset internal Xen state for the domain returning it to the point where it
176 * was created but leaving the domain's memory contents and vCPU contexts
177 * intact. This will allow the domain to start over and set up all Xen specific
178 * interfaces again.
179 */
180 #define SHUTDOWN_soft_reset 5
181 #define SHUTDOWN_MAX 5 /* Maximum valid shutdown reason. */
182
183 #endif /* __XEN_PUBLIC_SCHED_H__ */