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/*
55 * kern_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 *
61 * kern_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. The thread may be preempted after
135 * the computation time has elapsed.
136 * If (computation < constraint/2) it will be forced to
137 * constraint/2 to avoid unintended preemption and associated
138 * timer interrupts.
139 *
140 * constraint: This is the maximum amount of real time that
141 * may elapse from the start of a separate processing arrival
142 * to the end of computation for logically correct functioning,
143 * specified in absolute time units. Must be (>= computation).
144 * Note that latency = (constraint - computation).
145 *
146 * preemptible: IGNORED (This indicates that the computation may be
147 * interrupted, subject to the constraint specified above.)
148 */
149
150#define THREAD_TIME_CONSTRAINT_POLICY 2
151
152struct thread_time_constraint_policy {
153 uint32_t period;
154 uint32_t computation;
155 uint32_t constraint;
156 boolean_t preemptible;
157};
158
159typedef struct thread_time_constraint_policy \
160 thread_time_constraint_policy_data_t;
161typedef struct thread_time_constraint_policy \
162 *thread_time_constraint_policy_t;
163
164#define THREAD_TIME_CONSTRAINT_POLICY_COUNT ((mach_msg_type_number_t) \
165 (sizeof (thread_time_constraint_policy_data_t) / sizeof (integer_t)))
166
167/*
168 * THREAD_PRECEDENCE_POLICY:
169 *
170 * This may be used to indicate the relative value of the
171 * computation compared to the other threads in the task.
172 *
173 * Parameters:
174 *
175 * importance: The importance is specified as a signed value.
176 */
177
178#define THREAD_PRECEDENCE_POLICY 3
179
180struct thread_precedence_policy {
181 integer_t importance;
182};
183
184typedef struct thread_precedence_policy thread_precedence_policy_data_t;
185typedef struct thread_precedence_policy *thread_precedence_policy_t;
186
187#define THREAD_PRECEDENCE_POLICY_COUNT ((mach_msg_type_number_t) \
188 (sizeof (thread_precedence_policy_data_t) / sizeof (integer_t)))
189
190/*
191 * THREAD_AFFINITY_POLICY:
192 *
193 * This policy is experimental.
194 * This may be used to express affinity relationships
195 * between threads in the task. Threads with the same affinity tag will
196 * be scheduled to share an L2 cache if possible. That is, affinity tags
197 * are a hint to the scheduler for thread placement.
198 *
199 * The namespace of affinity tags is generally local to one task. However,
200 * a child task created after the assignment of affinity tags by its parent
201 * will share that namespace. In particular, a family of forked processes
202 * may be created with a shared affinity namespace.
203 *
204 * Parameters:
205 * tag: The affinity set identifier.
206 */
207
208#define THREAD_AFFINITY_POLICY 4
209
210struct thread_affinity_policy {
211 integer_t affinity_tag;
212};
213
214#define THREAD_AFFINITY_TAG_NULL 0
215
216typedef struct thread_affinity_policy thread_affinity_policy_data_t;
217typedef struct thread_affinity_policy *thread_affinity_policy_t;
218
219#define THREAD_AFFINITY_POLICY_COUNT ((mach_msg_type_number_t) \
220 (sizeof (thread_affinity_policy_data_t) / sizeof (integer_t)))
221
222/*
223 * THREAD_BACKGROUND_POLICY:
224 */
225
226#define THREAD_BACKGROUND_POLICY 5
227
228struct thread_background_policy {
229 integer_t priority;
230};
231
232#define THREAD_BACKGROUND_POLICY_DARWIN_BG 0x1000
233
234typedef struct thread_background_policy thread_background_policy_data_t;
235typedef struct thread_background_policy *thread_background_policy_t;
236
237#define THREAD_BACKGROUND_POLICY_COUNT ((mach_msg_type_number_t) \
238 (sizeof (thread_background_policy_data_t) / sizeof (integer_t)))
239
240
241#define THREAD_LATENCY_QOS_POLICY 7
242typedef integer_t thread_latency_qos_t;
243
244struct thread_latency_qos_policy {
245 thread_latency_qos_t thread_latency_qos_tier;
246};
247
248typedef struct thread_latency_qos_policy thread_latency_qos_policy_data_t;
249typedef struct thread_latency_qos_policy *thread_latency_qos_policy_t;
250
251#define THREAD_LATENCY_QOS_POLICY_COUNT ((mach_msg_type_number_t) \
252 (sizeof (thread_latency_qos_policy_data_t) / sizeof (integer_t)))
253
254#define THREAD_THROUGHPUT_QOS_POLICY 8
255typedef integer_t thread_throughput_qos_t;
256
257struct thread_throughput_qos_policy {
258 thread_throughput_qos_t thread_throughput_qos_tier;
259};
260
261typedef struct thread_throughput_qos_policy thread_throughput_qos_policy_data_t;
262typedef struct thread_throughput_qos_policy *thread_throughput_qos_policy_t;
263
264#define THREAD_THROUGHPUT_QOS_POLICY_COUNT ((mach_msg_type_number_t) \
265 (sizeof (thread_throughput_qos_policy_data_t) / sizeof (integer_t)))
266
267#ifdef PRIVATE
268#include <mach/thread_policy_private.h>
269#endif
270
271#endif /* _MACH_THREAD_POLICY_H_ */
272