1 /*
2 * Copyright (c) 2000-2017 Apple Computer, 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 _PTHREAD_PRIORITY_PRIVATE_H_
30 #define _PTHREAD_PRIORITY_PRIVATE_H_
31
32 /*!
33 * @typedef pthread_priority_t
34 *
35 * @abstract
36 * pthread_priority_t is an on opaque integer that is guaranteed to be ordered
37 * such that combations of QoS classes and relative priorities are ordered
38 * numerically, according to their combined priority.
39 *
40 * <b>xnu, pthread & libdispatch flags</b>
41 *
42 * @const _PTHREAD_PRIORITY_OVERCOMMIT_FLAG
43 * The thread this priority is applied to is overcommit (affects the workqueue
44 * creation policy for this priority).
45 *
46 * @const _PTHREAD_PRIORITY_FALLBACK_FLAG
47 * Indicates that this priority is is used only when incoming events have no
48 * priority at all. It is merely used as a fallback (hence the name) instead of
49 * a floor.
50 *
51 * This is usually used with QOS_CLASS_DEFAULT and a 0 relative priority.
52 *
53 * @const _PTHREAD_PRIORITY_EVENT_MANAGER_FLAG
54 * The event manager flag indicates that this thread/request is for a event
55 * manager thread. There can only ever be one event manager thread at a time
56 * and it is brought up at the highest of all event manager priorities pthread
57 * knows about.
58 *
59 * <b>pthread & dispatch only flags</b>
60 *
61 * @const _PTHREAD_PRIORITY_SCHED_PRI_FLAG
62 * @const _PTHREAD_PRIORITY_SCHED_PRI_MASK
63 * This flag indicates that the bits extracted using
64 * _PTHREAD_PRIORITY_SCHED_PRI_MASK represent a scheduler priority instead of
65 * a {qos, relative priority} pair.
66 *
67 * This flag is only used by the pthread kext to indicate libdispatch that the
68 * event manager queue priority is a scheduling priority and not a QoS. This
69 * flag is never used as an input by anything else and is why it can perform
70 * a double duty with _PTHREAD_PRIORITY_ROOTQUEUE_FLAG.
71 *
72 * @const _PTHREAD_PRIORITY_NEEDS_UNBIND_FLAG
73 * This flag is used for the priority of event delivery threads to indicate
74 * to libdispatch that this thread is bound to a kqueue.
75 *
76 * <b>dispatch only flags</b>
77 *
78 * @const _PTHREAD_PRIORITY_INHERIT_FLAG
79 * This flag is meaningful to libdispatch only and has no meanting for the
80 * kernel and/or pthread.
81 *
82 * @const _PTHREAD_PRIORITY_ROOTQUEUE_FLAG
83 * This flag is meaningful to libdispatch only and has no meanting for the
84 * kernel and/or pthread.
85 *
86 * @const _PTHREAD_PRIORITY_ENFORCE_FLAG
87 * This flag is used to indicate that this priority should be prefered for work
88 * submited asynchronously over the intrinsic priority of the queue/thread the
89 * work is submitted to.
90 *
91 * @const _PTHREAD_PRIORITY_COOPERATIVE_FLAG
92 * Used to convey that a thread is part of the cooperative pool
93 *
94 * @const _PTHREAD_PRIORITY_THREAD_TYPE_MASK
95 * The set of bits that encode information about the thread type - whether it is
96 * overcommit, non-overcommit or cooperative
97 */
98 typedef unsigned long pthread_priority_t;
99
100 #define _PTHREAD_PRIORITY_FLAGS_MASK 0xff000000u
101 #define _PTHREAD_PRIORITY_FLAGS_SHIFT (24ull)
102
103 #define _PTHREAD_PRIORITY_OVERCOMMIT_FLAG 0x80000000u
104 #define _PTHREAD_PRIORITY_INHERIT_FLAG 0x40000000u /* dispatch only */
105 #define _PTHREAD_PRIORITY_ROOTQUEUE_FLAG 0x20000000u /* dispatch only */
106 #define _PTHREAD_PRIORITY_SCHED_PRI_FLAG 0x20000000u
107 #define _PTHREAD_PRIORITY_SCHED_PRI_MASK 0x0000ffffu
108 #define _PTHREAD_PRIORITY_ENFORCE_FLAG 0x10000000u /* dispatch only */
109 #define _PTHREAD_PRIORITY_FALLBACK_FLAG 0x04000000u
110 #define _PTHREAD_PRIORITY_COOPERATIVE_FLAG 0x08000000u
111 #define _PTHREAD_PRIORITY_EVENT_MANAGER_FLAG 0x02000000u
112 #define _PTHREAD_PRIORITY_NEEDS_UNBIND_FLAG 0x01000000u
113 #define _PTHREAD_PRIORITY_DEFAULTQUEUE_FLAG _PTHREAD_PRIORITY_FALLBACK_FLAG // compat
114
115 #define _PTHREAD_PRIORITY_THREAD_TYPE_MASK (_PTHREAD_PRIORITY_COOPERATIVE_FLAG | _PTHREAD_PRIORITY_OVERCOMMIT_FLAG)
116
117 #define _PTHREAD_PRIORITY_ENCODING_MASK 0x00a00000u
118 #define _PTHREAD_PRIORITY_ENCODING_SHIFT (22ull)
119 #define _PTHREAD_PRIORITY_ENCODING_V0 0x00000000u
120 #define _PTHREAD_PRIORITY_ENCODING_V1 0x00400000u /* unused */
121 #define _PTHREAD_PRIORITY_ENCODING_V2 0x00800000u /* unused */
122 #define _PTHREAD_PRIORITY_ENCODING_V3 0x00a00000u /* unused */
123
124 #define _PTHREAD_PRIORITY_QOS_CLASS_MASK 0x003fff00u
125 #define _PTHREAD_PRIORITY_VALID_QOS_CLASS_MASK 0x00003f00u
126 #define _PTHREAD_PRIORITY_QOS_CLASS_SHIFT (8ull)
127
128 #define _PTHREAD_PRIORITY_PRIORITY_MASK 0x000000ffu
129 #define _PTHREAD_PRIORITY_PRIORITY_SHIFT (0)
130
131 #if PRIVATE
132 #if XNU_KERNEL_PRIVATE && !defined(__PTHREAD_EXPOSE_INTERNALS__)
133 #define __PTHREAD_EXPOSE_INTERNALS__ 1
134 #endif // XNU_KERNEL_PRIVATE
135 #ifdef __PTHREAD_EXPOSE_INTERNALS__
136 /*
137 * This exposes the encoding used for pthread_priority_t
138 * and is meant to be used by pthread and XNU only
139 */
140 #include <mach/thread_policy.h> // THREAD_QOS_*
141 #include <stdbool.h>
142
143 // pthread_priority_t's type is unfortunately 64bits on LP64
144 // so we use this type for people who need to store it in structs
145 typedef unsigned int pthread_priority_compact_t;
146
147 __attribute__((always_inline, const))
148 static inline bool
_pthread_priority_has_qos(pthread_priority_t pp)149 _pthread_priority_has_qos(pthread_priority_t pp)
150 {
151 return (pp & (_PTHREAD_PRIORITY_SCHED_PRI_FLAG |
152 _PTHREAD_PRIORITY_EVENT_MANAGER_FLAG)) == 0 &&
153 (pp & (_PTHREAD_PRIORITY_QOS_CLASS_MASK &
154 ~_PTHREAD_PRIORITY_VALID_QOS_CLASS_MASK)) == 0 &&
155 (pp & _PTHREAD_PRIORITY_VALID_QOS_CLASS_MASK) != 0;
156 }
157
158 __attribute__((always_inline, const))
159 static inline pthread_priority_compact_t
_pthread_priority_make_from_thread_qos(thread_qos_t qos,int relpri,unsigned long flags)160 _pthread_priority_make_from_thread_qos(thread_qos_t qos, int relpri,
161 unsigned long flags)
162 {
163 pthread_priority_compact_t pp = (flags & _PTHREAD_PRIORITY_FLAGS_MASK);
164 if (qos && qos < THREAD_QOS_LAST) {
165 pp |= (1 << (_PTHREAD_PRIORITY_QOS_CLASS_SHIFT + qos - 1));
166 pp |= ((uint8_t)relpri - 1) & _PTHREAD_PRIORITY_PRIORITY_MASK;
167 }
168 return pp;
169 }
170
171 __attribute__((always_inline, const))
172 static inline pthread_priority_compact_t
_pthread_event_manager_priority(void)173 _pthread_event_manager_priority(void)
174 {
175 return _PTHREAD_PRIORITY_EVENT_MANAGER_FLAG;
176 }
177
178 __attribute__((always_inline, const))
179 static inline pthread_priority_compact_t
_pthread_unspecified_priority(void)180 _pthread_unspecified_priority(void)
181 {
182 return _pthread_priority_make_from_thread_qos(THREAD_QOS_UNSPECIFIED, 0, 0);
183 }
184
185 __attribute__((always_inline, const))
186 static inline pthread_priority_compact_t
_pthread_default_priority(unsigned long flags)187 _pthread_default_priority(unsigned long flags)
188 {
189 return _pthread_priority_make_from_thread_qos(THREAD_QOS_LEGACY, 0, flags);
190 }
191
192 __attribute__((always_inline, const))
193 static inline thread_qos_t
_pthread_priority_thread_qos_fast(pthread_priority_t pp)194 _pthread_priority_thread_qos_fast(pthread_priority_t pp)
195 {
196 pp &= _PTHREAD_PRIORITY_QOS_CLASS_MASK;
197 pp >>= _PTHREAD_PRIORITY_QOS_CLASS_SHIFT;
198 return (thread_qos_t)__builtin_ffs((int)pp);
199 }
200
201 __attribute__((always_inline, const))
202 static inline thread_qos_t
_pthread_priority_thread_qos(pthread_priority_t pp)203 _pthread_priority_thread_qos(pthread_priority_t pp)
204 {
205 if (_pthread_priority_has_qos(pp)) {
206 return _pthread_priority_thread_qos_fast(pp);
207 }
208 return THREAD_QOS_UNSPECIFIED;
209 }
210
211 __attribute__((always_inline, const))
212 static inline int
_pthread_priority_relpri(pthread_priority_t pp)213 _pthread_priority_relpri(pthread_priority_t pp)
214 {
215 if (_pthread_priority_has_qos(pp)) {
216 pp &= _PTHREAD_PRIORITY_PRIORITY_MASK;
217 pp >>= _PTHREAD_PRIORITY_PRIORITY_SHIFT;
218 return (int8_t)pp + 1;
219 }
220 return 0;
221 }
222
223 __attribute__((always_inline, const))
224 static inline bool
_pthread_priority_is_overcommit(pthread_priority_t pp)225 _pthread_priority_is_overcommit(pthread_priority_t pp)
226 {
227 return pp & _PTHREAD_PRIORITY_OVERCOMMIT_FLAG;
228 }
229
230 __attribute__((always_inline, const))
231 static inline bool
_pthread_priority_is_cooperative(pthread_priority_t pp)232 _pthread_priority_is_cooperative(pthread_priority_t pp)
233 {
234 return pp & _PTHREAD_PRIORITY_COOPERATIVE_FLAG;
235 }
236
237 __attribute__((always_inline, const))
238 static inline bool
_pthread_priority_is_nonovercommit(pthread_priority_t pp)239 _pthread_priority_is_nonovercommit(pthread_priority_t pp)
240 {
241 return !_pthread_priority_is_cooperative(pp) && !_pthread_priority_is_overcommit(pp);
242 }
243
244 #if XNU_KERNEL_PRIVATE
245 // Interfaces only used by the kernel and not implemented in userspace.
246
247 /*
248 * Keep managerness, overcomitness and fallback, discard other flags.
249 * Normalize and validate QoS/relpri
250 */
251 __attribute__((const))
252 pthread_priority_compact_t
253 _pthread_priority_normalize(pthread_priority_t pp);
254
255 /*
256 * Keep managerness, discard other flags.
257 * Normalize and validate QoS/relpri
258 */
259 __attribute__((const))
260 pthread_priority_compact_t
261 _pthread_priority_normalize_for_ipc(pthread_priority_t pp);
262
263 /*
264 * Keep the flags from base_pp and return the priority with the maximum priority
265 * of base_pp and _pthread_priority_make_from_thread_qos(qos, 0, 0)
266 */
267 __attribute__((const))
268 pthread_priority_compact_t
269 _pthread_priority_combine(pthread_priority_t base_pp, thread_qos_t qos);
270
271 #endif // XNU_KERNEL_PRIVATE
272 #endif // __PTHREAD_EXPOSE_INTERNALS__
273 #endif // PRIVATE
274 #endif // _PTHREAD_PRIORITY_PRIVATE_H_
275