1 /* 2 * Copyright (c) 2022 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 29 #ifndef _MACH_THREAD_POLICY_PRIVATE_H_ 30 #define _MACH_THREAD_POLICY_PRIVATE_H_ 31 32 #include <mach/mach_types.h> 33 #include <mach/thread_policy.h> 34 35 /* 36 * THREAD_POLICY_STATE: 37 */ 38 #define THREAD_POLICY_STATE 6 39 40 #define THREAD_POLICY_STATE_FLAG_STATIC_PARAM 0x1 41 42 struct thread_policy_state { 43 integer_t requested; 44 integer_t effective; 45 integer_t pending; 46 integer_t flags; 47 uint64_t thps_requested_policy; 48 uint64_t thps_effective_policy; 49 uint32_t thps_user_promotions; 50 uint32_t thps_user_promotion_basepri; 51 uint32_t thps_ipc_overrides; 52 uint32_t reserved32; 53 uint64_t reserved[2]; 54 }; 55 56 typedef struct thread_policy_state thread_policy_state_data_t; 57 typedef struct thread_policy_state *thread_policy_state_t; 58 59 #define THREAD_POLICY_STATE_COUNT ((mach_msg_type_number_t) \ 60 (sizeof (thread_policy_state_data_t) / sizeof (integer_t))) 61 62 /* 63 * THREAD_QOS_POLICY: 64 */ 65 #define THREAD_QOS_POLICY 9 66 67 typedef uint8_t thread_qos_t; 68 #define THREAD_QOS_UNSPECIFIED 0 69 #define THREAD_QOS_DEFAULT THREAD_QOS_UNSPECIFIED /* Temporary rename */ 70 #define THREAD_QOS_MAINTENANCE 1 71 #define THREAD_QOS_BACKGROUND 2 72 #define THREAD_QOS_UTILITY 3 73 #define THREAD_QOS_LEGACY 4 /* i.e. default workq threads */ 74 #define THREAD_QOS_USER_INITIATED 5 75 #define THREAD_QOS_USER_INTERACTIVE 6 76 77 #define THREAD_QOS_LAST 7 78 79 #define THREAD_QOS_MIN_TIER_IMPORTANCE (-15) 80 81 /* 82 * Overrides are inputs to the task/thread policy engine that 83 * temporarily elevate the effective QoS of a thread without changing 84 * its steady-state (and round-trip-able) requested QoS. The 85 * interfaces into the kernel allow the caller to associate a resource 86 * and type that describe the reason/lifecycle of the override. For 87 * instance, a contended pthread_mutex_t held by a UTILITY thread 88 * might get an override to USER_INTERACTIVE, with the resource 89 * being the userspace address of the pthread_mutex_t. When the 90 * owning thread releases that resource, it can call into the 91 * task policy subsystem to drop the override because of that resource, 92 * although if more contended locks are held by the thread, the 93 * effective QoS may remain overridden for longer. 94 * 95 * THREAD_QOS_OVERRIDE_TYPE_PTHREAD_MUTEX is used for contended 96 * pthread_mutex_t's via the pthread kext. The holder gets an override 97 * with resource=&mutex and a count of 1 by the initial contender. 98 * Subsequent contenders raise the QoS value, until the holder 99 * decrements the count to 0 and the override is released. 100 * 101 * THREAD_QOS_OVERRIDE_TYPE_PTHREAD_RWLOCK is unimplemented and has no 102 * specified semantics. 103 * 104 * THREAD_QOS_OVERRIDE_TYPE_PTHREAD_EXPLICIT_OVERRIDE are explicitly 105 * paired start/end overrides on a target thread. The resource can 106 * either be a memory allocation in userspace, or the pthread_t of the 107 * overrider if no allocation was used. 108 * 109 * THREAD_QOS_OVERRIDE_TYPE_WILDCARD is a catch-all which will reset every 110 * resource matching the resource value. Passing 111 * THREAD_QOS_OVERRIDE_RESOURCE_WILDCARD as well will reset everything. 112 */ 113 114 #define THREAD_QOS_OVERRIDE_TYPE_UNKNOWN (0) 115 #define THREAD_QOS_OVERRIDE_TYPE_PTHREAD_MUTEX (1) 116 #define THREAD_QOS_OVERRIDE_TYPE_PTHREAD_RWLOCK (2) 117 #define THREAD_QOS_OVERRIDE_TYPE_PTHREAD_EXPLICIT_OVERRIDE (3) 118 #define THREAD_QOS_OVERRIDE_TYPE_WILDCARD (5) 119 120 /* A special resource value to indicate a resource wildcard */ 121 #define THREAD_QOS_OVERRIDE_RESOURCE_WILDCARD (~((user_addr_t)0)) 122 123 struct thread_qos_policy { 124 integer_t qos_tier; 125 integer_t tier_importance; 126 }; 127 128 typedef struct thread_qos_policy thread_qos_policy_data_t; 129 typedef struct thread_qos_policy *thread_qos_policy_t; 130 131 #define THREAD_QOS_POLICY_COUNT ((mach_msg_type_number_t) \ 132 (sizeof (thread_qos_policy_data_t) / sizeof (integer_t))) 133 134 /* 135 * THREAD_TIME_CONSTRAINT_WITH_PRIORITY_POLICY: 136 * 137 * This scheduling mode is for threads which have real time 138 * constraints on their execution with support for multiple 139 * real time priorities. 140 * 141 * Threads are ordered by highest priority first then, for 142 * threads of the same priority, by earliest deadline first. 143 * But if sched_rt_runq_strict_priority is false, a lower priority 144 * thread with an earlier deadline will be preferred over a higher 145 * priority thread with a later deadline, as long as both threads' 146 * computations will fit before the later deadline. 147 * 148 * Parameters: 149 * 150 * period: This is the nominal amount of time between separate 151 * processing arrivals, specified in absolute time units. A 152 * value of 0 indicates that there is no inherent periodicity in 153 * the computation. 154 * 155 * computation: This is the nominal amount of computation 156 * time needed during a separate processing arrival, specified 157 * in absolute time units. The thread may be preempted after 158 * the computation time has elapsed. 159 * If (computation < constraint/2) it will be forced to 160 * constraint/2 to avoid unintended preemption and associated 161 * timer interrupts. 162 * 163 * constraint: This is the maximum amount of real time that 164 * may elapse from the start of a separate processing arrival 165 * to the end of computation for logically correct functioning, 166 * specified in absolute time units. Must be (>= computation). 167 * Note that latency = (constraint - computation). 168 * 169 * preemptible: IGNORED (This indicates that the computation may be 170 * interrupted, subject to the constraint specified above.) 171 * 172 * priority: This is the scheduling priority of the thread. 173 * User processes may only set the default priority of 174 * TIME_CONSTRAINT_POLICY_DEFAULT_PRIORITY. Higher priorities 175 * up to TIME_CONSTRAINT_POLICY_MAXIMUM_PRIORITY are reserved 176 * for system use and attempts to set them will fail. 177 */ 178 179 #define THREAD_TIME_CONSTRAINT_WITH_PRIORITY_POLICY 10 180 181 struct thread_time_constraint_with_priority_policy { 182 uint32_t period; 183 uint32_t computation; 184 uint32_t constraint; 185 boolean_t preemptible; 186 uint32_t priority; 187 }; 188 189 typedef struct thread_time_constraint_with_priority_policy \ 190 thread_time_constraint_with_priority_policy_data_t; 191 typedef struct thread_time_constraint_with_priority_policy \ 192 *thread_time_constraint_with_priority_policy_t; 193 194 #define THREAD_TIME_CONSTRAINT_WITH_PRIORITY_POLICY_COUNT ((mach_msg_type_number_t) \ 195 (sizeof (thread_time_constraint_with_priority_policy_data_t) / sizeof (integer_t))) 196 197 #define TIME_CONSTRAINT_POLICY_DEFAULT_PRIORITY 97 198 #define TIME_CONSTRAINT_POLICY_MAXIMUM_PRIORITY 127 199 200 /* 201 * THREAD_REQUESTED_STATE_POLICY: Retrieves just the thread's requested qos policy 202 */ 203 #define THREAD_REQUESTED_STATE_POLICY 11 204 205 struct thread_requested_qos_policy { 206 integer_t thrq_base_qos; 207 integer_t thrq_qos_relprio; 208 integer_t thrq_qos_override; 209 integer_t thrq_qos_promote; 210 integer_t thrq_qos_kevent_override; 211 integer_t thrq_qos_workq_override; 212 integer_t thrq_qos_wlsvc_override; 213 }; 214 215 typedef struct thread_requested_qos_policy thread_requested_qos_policy_data_t; 216 typedef struct thread_requested_qos_policy *thread_requested_qos_policy_t; 217 218 #define THREAD_REQUESTED_STATE_POLICY_COUNT ((mach_msg_type_number_t) \ 219 (sizeof(thread_requested_qos_policy_data_t) / sizeof (integer_t))) 220 221 /* 222 * Internal bitfields are privately exported for revlocked tracing tools like 223 * msa to decode tracepoints. 224 * 225 * These struct definitions *will* change in the future. 226 * When they do, we will update THREAD_POLICY_INTERNAL_STRUCT_VERSION. 227 */ 228 229 #define THREAD_POLICY_INTERNAL_STRUCT_VERSION 7 230 231 struct thread_requested_policy { 232 uint64_t thrp_int_darwinbg :1, /* marked as darwinbg via setpriority */ 233 thrp_ext_darwinbg :1, 234 thrp_int_iotier :2, /* IO throttle tier */ 235 thrp_ext_iotier :2, 236 thrp_int_iopassive :1, /* should IOs cause lower tiers to be throttled */ 237 thrp_ext_iopassive :1, 238 thrp_latency_qos :3, /* Timer latency QoS */ 239 thrp_through_qos :3, /* Computation throughput QoS */ 240 241 thrp_pidbind_bg :1, /* task i'm bound to is marked 'watchbg' */ 242 thrp_qos :3, /* thread qos class */ 243 thrp_qos_relprio :4, /* thread qos relative priority (store as inverse, -10 -> 0xA) */ 244 thrp_qos_override :3, /* thread qos class override */ 245 thrp_qos_promote :3, /* thread qos class from promotion */ 246 thrp_qos_kevent_override:3, /* thread qos class from kevent override */ 247 thrp_terminated :1, /* heading for termination */ 248 thrp_qos_workq_override :3, /* thread qos class override (workq) */ 249 thrp_qos_wlsvc_override :3, /* workloop servicer qos class override */ 250 thrp_iotier_kevent_override :2, /* thread iotier from kevent override */ 251 thrp_wi_driven :1, /* thread priority from work interval */ 252 253 thrp_reserved :23; 254 }; 255 256 struct thread_effective_policy { 257 uint64_t thep_darwinbg :1, /* marked as 'background', and sockets are marked bg when created */ 258 thep_io_tier :2, /* effective throttle tier */ 259 thep_io_passive :1, /* should IOs cause lower tiers to be throttled */ 260 thep_all_sockets_bg :1, /* All existing sockets in process are marked as bg (thread: all created by thread) */ 261 thep_new_sockets_bg :1, /* Newly created sockets should be marked as bg */ 262 thep_terminated :1, /* all throttles have been removed for quick exit or SIGTERM handling */ 263 thep_qos_ui_is_urgent :1, /* bump UI-Interactive QoS up to the urgent preemption band */ 264 thep_latency_qos :3, /* Timer latency QoS level */ 265 thep_through_qos :3, /* Computation throughput QoS level */ 266 267 thep_qos :3, /* thread qos class */ 268 thep_qos_relprio :4, /* thread qos relative priority (store as inverse, -10 -> 0xA) */ 269 thep_qos_promote :3, /* thread qos class used for promotion */ 270 thep_promote_above_task :1, /* thread is promoted above task-level clamp */ 271 thep_wi_driven :1, /* thread priority is driven by work interval */ 272 273 thep_reserved :38; 274 }; 275 276 #endif 277