Line data Source code
1 0 : /* SPDX-License-Identifier: MIT */
2 :
3 : /******************************************************************************
4 : * sched.h
5 : *
6 : * Scheduler state interactions
7 : *
8 : * Permission is hereby granted, free of charge, to any person obtaining a copy
9 : * of this software and associated documentation files (the "Software"), to
10 : * deal in the Software without restriction, including without limitation the
11 : * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
12 : * sell copies of the Software, and to permit persons to whom the Software is
13 : * furnished to do so, subject to the following conditions:
14 : *
15 : * The above copyright notice and this permission notice shall be included in
16 : * all copies or substantial portions of the Software.
17 : *
18 : * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 : * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 : * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 : * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 : * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
23 : * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
24 : * DEALINGS IN THE SOFTWARE.
25 : *
26 : * Copyright (c) 2005, Keir Fraser <keir@xensource.com>
27 : */
28 :
29 : #ifndef __XEN_PUBLIC_SCHED_H__
30 : #define __XEN_PUBLIC_SCHED_H__
31 :
32 : #include "event_channel.h"
33 :
34 : /*
35 : * `incontents 150 sched Guest Scheduler Operations
36 : *
37 : * The SCHEDOP interface provides mechanisms for a guest to interact
38 : * with the scheduler, including yield, blocking and shutting itself
39 : * down.
40 : */
41 :
42 : /*
43 : * The prototype for this hypercall is:
44 : * ` long HYPERVISOR_sched_op(enum sched_op cmd, void *arg, ...)
45 : *
46 : * @cmd == SCHEDOP_??? (scheduler operation).
47 : * @arg == Operation-specific extra argument(s), as described below.
48 : * ... == Additional Operation-specific extra arguments, described below.
49 : *
50 : * Versions of Xen prior to 3.0.2 provided only the following legacy version
51 : * of this hypercall, supporting only the commands yield, block and shutdown:
52 : * long sched_op(int cmd, unsigned long arg)
53 : * @cmd == SCHEDOP_??? (scheduler operation).
54 : * @arg == 0 (SCHEDOP_yield and SCHEDOP_block)
55 : * == SHUTDOWN_* code (SCHEDOP_shutdown)
56 : *
57 : * This legacy version is available to new guests as:
58 : * ` long HYPERVISOR_sched_op_compat(enum sched_op cmd, unsigned long arg)
59 : */
60 :
61 : /*
62 : * Voluntarily yield the CPU.
63 : * @arg == NULL.
64 : */
65 0 : #define SCHEDOP_yield 0
66 :
67 : /*
68 : * Block execution of this VCPU until an event is received for processing.
69 : * If called with event upcalls masked, this operation will atomically
70 : * reenable event delivery and check for pending events before blocking the
71 : * VCPU. This avoids a "wakeup waiting" race.
72 : * @arg == NULL.
73 : */
74 0 : #define SCHEDOP_block 1
75 :
76 : /*
77 : * Halt execution of this domain (all VCPUs) and notify the system controller.
78 : * @arg == pointer to sched_shutdown_t structure.
79 : *
80 : * If the sched_shutdown_t reason is SHUTDOWN_suspend then
81 : * x86 PV guests must also set RDX (EDX for 32-bit guests) to the MFN
82 : * of the guest's start info page. RDX/EDX is the third hypercall
83 : * argument.
84 : *
85 : * In addition, which reason is SHUTDOWN_suspend this hypercall
86 : * returns 1 if suspend was cancelled or the domain was merely
87 : * checkpointed, and 0 if it is resuming in a new domain.
88 : */
89 0 : #define SCHEDOP_shutdown 2
90 :
91 : /*
92 : * Poll a set of event-channel ports. Return when one or more are pending. An
93 : * optional timeout may be specified.
94 : * @arg == pointer to sched_poll_t structure.
95 : */
96 0 : #define SCHEDOP_poll 3
97 :
98 : /*
99 : * Declare a shutdown for another domain. The main use of this function is
100 : * in interpreting shutdown requests and reasons for fully-virtualized
101 : * domains. A para-virtualized domain may use SCHEDOP_shutdown directly.
102 : * @arg == pointer to sched_remote_shutdown_t structure.
103 : */
104 0 : #define SCHEDOP_remote_shutdown 4
105 :
106 : /*
107 : * Latch a shutdown code, so that when the domain later shuts down it
108 : * reports this code to the control tools.
109 : * @arg == sched_shutdown_t, as for SCHEDOP_shutdown.
110 : */
111 0 : #define SCHEDOP_shutdown_code 5
112 :
113 : /*
114 : * Setup, poke and destroy a domain watchdog timer.
115 : * @arg == pointer to sched_watchdog_t structure.
116 : * With id == 0, setup a domain watchdog timer to cause domain shutdown
117 : * after timeout, returns watchdog id.
118 : * With id != 0 and timeout == 0, destroy domain watchdog timer.
119 : * With id != 0 and timeout != 0, poke watchdog timer and set new timeout.
120 : */
121 0 : #define SCHEDOP_watchdog 6
122 :
123 : /*
124 : * Override the current vcpu affinity by pinning it to one physical cpu or
125 : * undo this override restoring the previous affinity.
126 : * @arg == pointer to sched_pin_override_t structure.
127 : *
128 : * A negative pcpu value will undo a previous pin override and restore the
129 : * previous cpu affinity.
130 : * This call is allowed for the hardware domain only and requires the cpu
131 : * to be part of the domain's cpupool.
132 : */
133 0 : #define SCHEDOP_pin_override 7
134 :
135 0 : struct sched_shutdown {
136 0 : unsigned int reason; /* SHUTDOWN_* => enum sched_shutdown_reason */
137 : };
138 0 : typedef struct sched_shutdown sched_shutdown_t;
139 0 : DEFINE_XEN_GUEST_HANDLE(sched_shutdown_t);
140 :
141 0 : struct sched_poll {
142 0 : XEN_GUEST_HANDLE(evtchn_port_t) ports;
143 0 : unsigned int nr_ports;
144 0 : uint64_t timeout;
145 : };
146 0 : typedef struct sched_poll sched_poll_t;
147 0 : DEFINE_XEN_GUEST_HANDLE(sched_poll_t);
148 :
149 0 : struct sched_remote_shutdown {
150 0 : domid_t domain_id; /* Remote domain ID */
151 0 : unsigned int reason; /* SHUTDOWN_* => enum sched_shutdown_reason */
152 : };
153 0 : typedef struct sched_remote_shutdown sched_remote_shutdown_t;
154 0 : DEFINE_XEN_GUEST_HANDLE(sched_remote_shutdown_t);
155 :
156 0 : struct sched_watchdog {
157 0 : uint32_t id; /* watchdog ID */
158 0 : uint32_t timeout; /* timeout */
159 : };
160 0 : typedef struct sched_watchdog sched_watchdog_t;
161 0 : DEFINE_XEN_GUEST_HANDLE(sched_watchdog_t);
162 :
163 0 : struct sched_pin_override {
164 0 : int32_t pcpu;
165 : };
166 0 : typedef struct sched_pin_override sched_pin_override_t;
167 0 : 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 : /* Domain exited normally. Clean up and kill. */
175 0 : #define SHUTDOWN_poweroff 0
176 :
177 : /* Clean up, kill, and then restart. */
178 0 : #define SHUTDOWN_reboot 1
179 :
180 : /* Clean up, save suspend info, kill. */
181 0 : #define SHUTDOWN_suspend 2
182 :
183 : /* Tell controller we've crashed. */
184 0 : #define SHUTDOWN_crash 3
185 :
186 : /* Restart because watchdog time expired. */
187 0 : #define SHUTDOWN_watchdog 4
188 :
189 : /*
190 : * Domain asked to perform 'soft reset' for it. The expected behavior is to
191 : * reset internal Xen state for the domain returning it to the point where it
192 : * was created but leaving the domain's memory contents and vCPU contexts
193 : * intact. This will allow the domain to start over and set up all Xen specific
194 : * interfaces again.
195 : */
196 0 : #define SHUTDOWN_soft_reset 5
197 :
198 : /* Maximum valid shutdown reason. */
199 0 : #define SHUTDOWN_MAX 5
200 :
201 : #endif /* __XEN_PUBLIC_SCHED_H__ */
|
