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