1/*
2 * Copyright (c) 2000-2007 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_H_
30#define _MACH_THREAD_POLICY_H_
31
32#include <mach/mach_types.h>
33
34/*
35 * These are the calls for accessing the policy parameters
36 * of a particular thread.
37 *
38 * The extra 'get_default' parameter to the second call is
39 * IN/OUT as follows:
40 * 1) if asserted on the way in it indicates that the default
41 * values should be returned, not the ones currently set, in
42 * this case 'get_default' will always be asserted on return;
43 * 2) if unasserted on the way in, the current settings are
44 * desired and if still unasserted on return, then the info
45 * returned reflects the current settings, otherwise if
46 * 'get_default' returns asserted, it means that there are no
47 * current settings due to other parameters taking precedence,
48 * and the default ones are being returned instead.
49 */
50
51typedef natural_t thread_policy_flavor_t;
52typedef integer_t *thread_policy_t;
53
54/*
55kern_return_t thread_policy_set(
56 thread_t thread,
57 thread_policy_flavor_t flavor,
58 thread_policy_t policy_info,
59 mach_msg_type_number_t count);
60
61kern_return_t thread_policy_get(
62 thread_t thread,
63 thread_policy_flavor_t flavor,
64 thread_policy_t policy_info,
65 mach_msg_type_number_t *count,
66 boolean_t *get_default);
67*/
68
69/*
70 * Defined flavors.
71 */
72/*
73 * THREAD_STANDARD_POLICY:
74 *
75 * This is the standard (fair) scheduling mode, assigned to new
76 * threads. The thread will be given processor time in a manner
77 * which apportions approximately equal share to long running
78 * computations.
79 *
80 * Parameters:
81 * [none]
82 */
83
84#define THREAD_STANDARD_POLICY 1
85
86struct thread_standard_policy {
87 natural_t no_data;
88};
89
90typedef struct thread_standard_policy thread_standard_policy_data_t;
91typedef struct thread_standard_policy *thread_standard_policy_t;
92
93#define THREAD_STANDARD_POLICY_COUNT 0
94
95/*
96 * THREAD_EXTENDED_POLICY:
97 *
98 * Extended form of THREAD_STANDARD_POLICY, which supplies a
99 * hint indicating whether this is a long running computation.
100 *
101 * Parameters:
102 *
103 * timeshare: TRUE (the default) results in identical scheduling
104 * behavior as THREAD_STANDARD_POLICY.
105 */
106
107#define THREAD_EXTENDED_POLICY 1
108
109struct thread_extended_policy {
110 boolean_t timeshare;
111};
112
113typedef struct thread_extended_policy thread_extended_policy_data_t;
114typedef struct thread_extended_policy *thread_extended_policy_t;
115
116#define THREAD_EXTENDED_POLICY_COUNT ((mach_msg_type_number_t) \
117 (sizeof (thread_extended_policy_data_t) / sizeof (integer_t)))
118
119/*
120 * THREAD_TIME_CONSTRAINT_POLICY:
121 *
122 * This scheduling mode is for threads which have real time
123 * constraints on their execution.
124 *
125 * Parameters:
126 *
127 * period: This is the nominal amount of time between separate
128 * processing arrivals, specified in absolute time units. A
129 * value of 0 indicates that there is no inherent periodicity in
130 * the computation.
131 *
132 * computation: This is the nominal amount of computation
133 * time needed during a separate processing arrival, specified
134 * in absolute time units.
135 *
136 * constraint: This is the maximum amount of real time that
137 * may elapse from the start of a separate processing arrival
138 * to the end of computation for logically correct functioning,
139 * specified in absolute time units. Must be (>= computation).
140 * Note that latency = (constraint - computation).
141 *
142 * preemptible: This indicates that the computation may be
143 * interrupted, subject to the constraint specified above.
144 */
145
146#define THREAD_TIME_CONSTRAINT_POLICY 2
147
148struct thread_time_constraint_policy {
149 uint32_t period;
150 uint32_t computation;
151 uint32_t constraint;
152 boolean_t preemptible;
153};
154
155typedef struct thread_time_constraint_policy \
156 thread_time_constraint_policy_data_t;
157typedef struct thread_time_constraint_policy \
158 *thread_time_constraint_policy_t;
159
160#define THREAD_TIME_CONSTRAINT_POLICY_COUNT ((mach_msg_type_number_t) \
161 (sizeof (thread_time_constraint_policy_data_t) / sizeof (integer_t)))
162
163/*
164 * THREAD_PRECEDENCE_POLICY:
165 *
166 * This may be used to indicate the relative value of the
167 * computation compared to the other threads in the task.
168 *
169 * Parameters:
170 *
171 * importance: The importance is specified as a signed value.
172 */
173
174#define THREAD_PRECEDENCE_POLICY 3
175
176struct thread_precedence_policy {
177 integer_t importance;
178};
179
180typedef struct thread_precedence_policy thread_precedence_policy_data_t;
181typedef struct thread_precedence_policy *thread_precedence_policy_t;
182
183#define THREAD_PRECEDENCE_POLICY_COUNT ((mach_msg_type_number_t) \
184 (sizeof (thread_precedence_policy_data_t) / sizeof (integer_t)))
185
186/*
187 * THREAD_AFFINITY_POLICY:
188 *
189 * This policy is experimental.
190 * This may be used to express affinity relationships
191 * between threads in the task. Threads with the same affinity tag will
192 * be scheduled to share an L2 cache if possible. That is, affinity tags
193 * are a hint to the scheduler for thread placement.
194 *
195 * The namespace of affinity tags is generally local to one task. However,
196 * a child task created after the assignment of affinity tags by its parent
197 * will share that namespace. In particular, a family of forked processes
198 * may be created with a shared affinity namespace.
199 *
200 * Parameters:
201 * tag: The affinity set identifier.
202 */
203
204#define THREAD_AFFINITY_POLICY 4
205
206struct thread_affinity_policy {
207 integer_t affinity_tag;
208};
209
210#define THREAD_AFFINITY_TAG_NULL 0
211
212typedef struct thread_affinity_policy thread_affinity_policy_data_t;
213typedef struct thread_affinity_policy *thread_affinity_policy_t;
214
215#define THREAD_AFFINITY_POLICY_COUNT ((mach_msg_type_number_t) \
216 (sizeof (thread_affinity_policy_data_t) / sizeof (integer_t)))
217
218/*
219 * THREAD_BACKGROUND_POLICY:
220 */
221
222#define THREAD_BACKGROUND_POLICY 5
223
224struct thread_background_policy {
225 integer_t priority;
226};
227
228#define THREAD_BACKGROUND_POLICY_DARWIN_BG 0x1000
229
230typedef struct thread_background_policy thread_background_policy_data_t;
231typedef struct thread_background_policy *thread_background_policy_t;
232
233#define THREAD_BACKGROUND_POLICY_COUNT ((mach_msg_type_number_t) \
234 (sizeof (thread_background_policy_data_t) / sizeof (integer_t)))
235
236
237#define THREAD_LATENCY_QOS_POLICY 7
238typedef integer_t thread_latency_qos_t;
239
240struct thread_latency_qos_policy {
241 thread_latency_qos_t thread_latency_qos_tier;
242};
243
244typedef struct thread_latency_qos_policy thread_latency_qos_policy_data_t;
245typedef struct thread_latency_qos_policy *thread_latency_qos_policy_t;
246
247#define THREAD_LATENCY_QOS_POLICY_COUNT ((mach_msg_type_number_t) \
248 (sizeof (thread_latency_qos_policy_data_t) / sizeof (integer_t)))
249
250#define THREAD_THROUGHPUT_QOS_POLICY 8
251typedef integer_t thread_throughput_qos_t;
252
253struct thread_throughput_qos_policy {
254 thread_throughput_qos_t thread_throughput_qos_tier;
255};
256
257typedef struct thread_throughput_qos_policy thread_throughput_qos_policy_data_t;
258typedef struct thread_throughput_qos_policy *thread_throughput_qos_policy_t;
259
260#define THREAD_THROUGHPUT_QOS_POLICY_COUNT ((mach_msg_type_number_t) \
261 (sizeof (thread_throughput_qos_policy_data_t) / sizeof (integer_t)))
262
263#ifdef PRIVATE
264
265/*
266 * THREAD_POLICY_STATE:
267 */
268#define THREAD_POLICY_STATE 6
269
270#define THREAD_POLICY_STATE_FLAG_STATIC_PARAM 0x1
271
272struct thread_policy_state {
273 integer_t requested;
274 integer_t effective;
275 integer_t pending;
276 integer_t flags;
277 uint64_t thps_requested_policy;
278 uint64_t thps_effective_policy;
279 uint32_t thps_user_promotions;
280 uint32_t thps_user_promotion_basepri;
281 uint32_t thps_ipc_overrides;
282 uint32_t reserved32;
283 uint64_t reserved[2];
284};
285
286typedef struct thread_policy_state thread_policy_state_data_t;
287typedef struct thread_policy_state *thread_policy_state_t;
288
289#define THREAD_POLICY_STATE_COUNT ((mach_msg_type_number_t) \
290 (sizeof (thread_policy_state_data_t) / sizeof (integer_t)))
291
292/*
293 * THREAD_QOS_POLICY:
294 */
295#define THREAD_QOS_POLICY 9
296#define THREAD_QOS_POLICY_OVERRIDE 10
297
298typedef uint8_t thread_qos_t;
299#define THREAD_QOS_UNSPECIFIED 0
300#define THREAD_QOS_DEFAULT THREAD_QOS_UNSPECIFIED /* Temporary rename */
301#define THREAD_QOS_MAINTENANCE 1
302#define THREAD_QOS_BACKGROUND 2
303#define THREAD_QOS_UTILITY 3
304#define THREAD_QOS_LEGACY 4 /* i.e. default workq threads */
305#define THREAD_QOS_USER_INITIATED 5
306#define THREAD_QOS_USER_INTERACTIVE 6
307
308#define THREAD_QOS_LAST 7
309
310#define THREAD_QOS_MIN_TIER_IMPORTANCE (-15)
311
312/*
313 * Overrides are inputs to the task/thread policy engine that
314 * temporarily elevate the effective QoS of a thread without changing
315 * its steady-state (and round-trip-able) requested QoS. The
316 * interfaces into the kernel allow the caller to associate a resource
317 * and type that describe the reason/lifecycle of the override. For
318 * instance, a contended pthread_mutex_t held by a UTILITY thread
319 * might get an override to USER_INTERACTIVE, with the resource
320 * being the userspace address of the pthread_mutex_t. When the
321 * owning thread releases that resource, it can call into the
322 * task policy subsystem to drop the override because of that resource,
323 * although if more contended locks are held by the thread, the
324 * effective QoS may remain overridden for longer.
325 *
326 * THREAD_QOS_OVERRIDE_TYPE_PTHREAD_MUTEX is used for contended
327 * pthread_mutex_t's via the pthread kext. The holder gets an override
328 * with resource=&mutex and a count of 1 by the initial contender.
329 * Subsequent contenders raise the QoS value, until the holder
330 * decrements the count to 0 and the override is released.
331 *
332 * THREAD_QOS_OVERRIDE_TYPE_PTHREAD_RWLOCK is unimplemented and has no
333 * specified semantics.
334 *
335 * THREAD_QOS_OVERRIDE_TYPE_PTHREAD_EXPLICIT_OVERRIDE are explicitly
336 * paired start/end overrides on a target thread. The resource can
337 * either be a memory allocation in userspace, or the pthread_t of the
338 * overrider if no allocation was used.
339 *
340 * THREAD_QOS_OVERRIDE_TYPE_WILDCARD is a catch-all which will reset every
341 * resource matching the resource value. Passing
342 * THREAD_QOS_OVERRIDE_RESOURCE_WILDCARD as well will reset everything.
343 */
344
345#define THREAD_QOS_OVERRIDE_TYPE_UNKNOWN (0)
346#define THREAD_QOS_OVERRIDE_TYPE_PTHREAD_MUTEX (1)
347#define THREAD_QOS_OVERRIDE_TYPE_PTHREAD_RWLOCK (2)
348#define THREAD_QOS_OVERRIDE_TYPE_PTHREAD_EXPLICIT_OVERRIDE (3)
349#define THREAD_QOS_OVERRIDE_TYPE_WILDCARD (5)
350
351/* A special resource value to indicate a resource wildcard */
352#define THREAD_QOS_OVERRIDE_RESOURCE_WILDCARD (~((user_addr_t)0))
353
354struct thread_qos_policy {
355 integer_t qos_tier;
356 integer_t tier_importance;
357};
358
359typedef struct thread_qos_policy thread_qos_policy_data_t;
360typedef struct thread_qos_policy *thread_qos_policy_t;
361
362#define THREAD_QOS_POLICY_COUNT ((mach_msg_type_number_t) \
363 (sizeof (thread_qos_policy_data_t) / sizeof (integer_t)))
364
365#endif /* PRIVATE */
366
367#ifdef PRIVATE
368
369/*
370 * Internal bitfields are privately exported for revlocked tracing tools like msa to decode tracepoints.
371 *
372 * These struct definitions *will* change in the future.
373 * When they do, we will update THREAD_POLICY_INTERNAL_STRUCT_VERSION.
374 */
375
376#define THREAD_POLICY_INTERNAL_STRUCT_VERSION 5
377
378struct thread_requested_policy {
379 uint64_t thrp_int_darwinbg :1, /* marked as darwinbg via setpriority */
380 thrp_ext_darwinbg :1,
381 thrp_int_iotier :2, /* IO throttle tier */
382 thrp_ext_iotier :2,
383 thrp_int_iopassive :1, /* should IOs cause lower tiers to be throttled */
384 thrp_ext_iopassive :1,
385 thrp_latency_qos :3, /* Timer latency QoS */
386 thrp_through_qos :3, /* Computation throughput QoS */
387
388 thrp_pidbind_bg :1, /* task i'm bound to is marked 'watchbg' */
389 thrp_qos :3, /* thread qos class */
390 thrp_qos_relprio :4, /* thread qos relative priority (store as inverse, -10 -> 0xA) */
391 thrp_qos_override :3, /* thread qos class override */
392 thrp_qos_promote :3, /* thread qos class from promotion */
393 thrp_qos_ipc_override :3, /* thread qos class from ipc override */
394 thrp_terminated :1, /* heading for termination */
395 thrp_qos_sync_ipc_override:3, /* now unused */
396 thrp_qos_workq_override :3, /* thread qos class override (workq) */
397
398 thrp_reserved :26;
399};
400
401struct thread_effective_policy {
402 uint64_t thep_darwinbg :1, /* marked as 'background', and sockets are marked bg when created */
403 thep_io_tier :2, /* effective throttle tier */
404 thep_io_passive :1, /* should IOs cause lower tiers to be throttled */
405 thep_all_sockets_bg :1, /* All existing sockets in process are marked as bg (thread: all created by thread) */
406 thep_new_sockets_bg :1, /* Newly created sockets should be marked as bg */
407 thep_terminated :1, /* all throttles have been removed for quick exit or SIGTERM handling */
408 thep_qos_ui_is_urgent :1, /* bump UI-Interactive QoS up to the urgent preemption band */
409 thep_latency_qos :3, /* Timer latency QoS level */
410 thep_through_qos :3, /* Computation throughput QoS level */
411
412 thep_qos :3, /* thread qos class */
413 thep_qos_relprio :4, /* thread qos relative priority (store as inverse, -10 -> 0xA) */
414 thep_qos_promote :3, /* thread qos class used for promotion */
415
416 thep_reserved :40;
417};
418
419#endif /* PRIVATE */
420
421
422#endif /* _MACH_THREAD_POLICY_H_ */
423