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 "event_channel.h"
31 
32 /*
33  * `incontents 150 sched 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 /* ` enum sched_op { // SCHEDOP_* => struct sched_* */
60 /*
61  * Voluntarily yield the CPU.
62  * @arg == NULL.
63  */
64 #define SCHEDOP_yield       0
65 
66 /*
67  * Block execution of this VCPU until an event is received for processing.
68  * If called with event upcalls masked, this operation will atomically
69  * reenable event delivery and check for pending events before blocking the
70  * VCPU. This avoids a "wakeup waiting" race.
71  * @arg == NULL.
72  */
73 #define SCHEDOP_block       1
74 
75 /*
76  * Halt execution of this domain (all VCPUs) and notify the system controller.
77  * @arg == pointer to sched_shutdown_t structure.
78  *
79  * If the sched_shutdown_t reason is SHUTDOWN_suspend then
80  * x86 PV guests must also set RDX (EDX for 32-bit guests) to the MFN
81  * of the guest's start info page.  RDX/EDX is the third hypercall
82  * argument.
83  *
84  * In addition, which reason is SHUTDOWN_suspend this hypercall
85  * returns 1 if suspend was cancelled or the domain was merely
86  * checkpointed, and 0 if it is resuming in a new domain.
87  */
88 #define SCHEDOP_shutdown    2
89 
90 /*
91  * Poll a set of event-channel ports. Return when one or more are pending. An
92  * optional timeout may be specified.
93  * @arg == pointer to sched_poll_t structure.
94  */
95 #define SCHEDOP_poll        3
96 
97 /*
98  * Declare a shutdown for another domain. The main use of this function is
99  * in interpreting shutdown requests and reasons for fully-virtualized
100  * domains.  A para-virtualized domain may use SCHEDOP_shutdown directly.
101  * @arg == pointer to sched_remote_shutdown_t structure.
102  */
103 #define SCHEDOP_remote_shutdown        4
104 
105 /*
106  * Latch a shutdown code, so that when the domain later shuts down it
107  * reports this code to the control tools.
108  * @arg == sched_shutdown_t, as for SCHEDOP_shutdown.
109  */
110 #define SCHEDOP_shutdown_code 5
111 
112 /*
113  * Setup, poke and destroy a domain watchdog timer.
114  * @arg == pointer to sched_watchdog_t structure.
115  * With id == 0, setup a domain watchdog timer to cause domain shutdown
116  *               after timeout, returns watchdog id.
117  * With id != 0 and timeout == 0, destroy domain watchdog timer.
118  * With id != 0 and timeout != 0, poke watchdog timer and set new timeout.
119  */
120 #define SCHEDOP_watchdog    6
121 
122 /*
123  * Override the current vcpu affinity by pinning it to one physical cpu or
124  * undo this override restoring the previous affinity.
125  * @arg == pointer to sched_pin_override_t structure.
126  *
127  * A negative pcpu value will undo a previous pin override and restore the
128  * previous cpu affinity.
129  * This call is allowed for the hardware domain only and requires the cpu
130  * to be part of the domain's cpupool.
131  */
132 #define SCHEDOP_pin_override 7
133 /* ` } */
134 
135 struct sched_shutdown {
136     unsigned int reason; /* SHUTDOWN_* => enum sched_shutdown_reason */
137 };
138 typedef struct sched_shutdown sched_shutdown_t;
139 DEFINE_XEN_GUEST_HANDLE(sched_shutdown_t);
140 
141 struct sched_poll {
142     XEN_GUEST_HANDLE(evtchn_port_t) ports;
143     unsigned int nr_ports;
144     uint64_t timeout;
145 };
146 typedef struct sched_poll sched_poll_t;
147 DEFINE_XEN_GUEST_HANDLE(sched_poll_t);
148 
149 struct sched_remote_shutdown {
150     domid_t domain_id;         /* Remote domain ID */
151     unsigned int reason;       /* SHUTDOWN_* => enum sched_shutdown_reason */
152 };
153 typedef struct sched_remote_shutdown sched_remote_shutdown_t;
154 DEFINE_XEN_GUEST_HANDLE(sched_remote_shutdown_t);
155 
156 struct sched_watchdog {
157     uint32_t id;                /* watchdog ID */
158     uint32_t timeout;           /* timeout */
159 };
160 typedef struct sched_watchdog sched_watchdog_t;
161 DEFINE_XEN_GUEST_HANDLE(sched_watchdog_t);
162 
163 struct sched_pin_override {
164     int32_t pcpu;
165 };
166 typedef struct sched_pin_override sched_pin_override_t;
167 DEFINE_XEN_GUEST_HANDLE(sched_pin_override_t);
168 
169 /*
170  * Reason codes for SCHEDOP_shutdown. These may be interpreted by control
171  * software to determine the appropriate action. For the most part, Xen does
172  * not care about the shutdown code.
173  */
174 /* ` enum sched_shutdown_reason { */
175 #define SHUTDOWN_poweroff   0  /* Domain exited normally. Clean up and kill. */
176 #define SHUTDOWN_reboot     1  /* Clean up, kill, and then restart.          */
177 #define SHUTDOWN_suspend    2  /* Clean up, save suspend info, kill.         */
178 #define SHUTDOWN_crash      3  /* Tell controller we've crashed.             */
179 #define SHUTDOWN_watchdog   4  /* Restart because watchdog time expired.     */
180 
181 /*
182  * Domain asked to perform 'soft reset' for it. The expected behavior is to
183  * reset internal Xen state for the domain returning it to the point where it
184  * was created but leaving the domain's memory contents and vCPU contexts
185  * intact. This will allow the domain to start over and set up all Xen specific
186  * interfaces again.
187  */
188 #define SHUTDOWN_soft_reset 5
189 #define SHUTDOWN_MAX        5  /* Maximum valid shutdown reason.             */
190 /* ` } */
191 
192 #endif /* __XEN_PUBLIC_SCHED_H__ */
193 
194 /*
195  * Local variables:
196  * mode: C
197  * c-file-style: "BSD"
198  * c-basic-offset: 4
199  * tab-width: 4
200  * indent-tabs-mode: nil
201  * End:
202  */
203