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 | |