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
42struct 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
56typedef struct thread_policy_state thread_policy_state_data_t;
57typedef 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
67typedef 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
123struct thread_qos_policy {
124 integer_t qos_tier;
125 integer_t tier_importance;
126};
127
128typedef struct thread_qos_policy thread_qos_policy_data_t;
129typedef 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
181struct 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
189typedef struct thread_time_constraint_with_priority_policy \
190 thread_time_constraint_with_priority_policy_data_t;
191typedef 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
205struct 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
215typedef struct thread_requested_qos_policy thread_requested_qos_policy_data_t;
216typedef 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
231struct 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
256struct 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