1 | /* |
2 | * Copyright (c) 2013 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 | #ifndef _IPC_IPC_IMPORTANCE_H_ |
29 | #define _IPC_IPC_IMPORTANCE_H_ |
30 | |
31 | #include <mach/mach_types.h> |
32 | #include <mach/mach_voucher_types.h> |
33 | #include <mach/boolean.h> |
34 | #include <ipc/ipc_types.h> |
35 | #include <ipc/ipc_voucher.h> |
36 | |
37 | /* |
38 | * IPC Importance - All definitions are MACH_KERNEL_PRIVATE |
39 | */ |
40 | #ifdef MACH_KERNEL_PRIVATE |
41 | |
42 | #include <kern/locks.h> |
43 | #include <kern/simple_lock.h> |
44 | |
45 | /* |
46 | * IPC Importance Value Element |
47 | * |
48 | * This element represents a single task's (base) importance, |
49 | * or in the case of inherited importance, the inheritance |
50 | * linkage from the source to the destination task. In the |
51 | * inheritance case, this source can be a base importance or |
52 | * another inherited importace. |
53 | * |
54 | * Whenever the task importance is adjusted, it walks the |
55 | * list of IPC-related items it influences (ports and downstream |
56 | * tasks doing work on its behalf) and makes adjustments to |
57 | * their importance attributes accordingly. |
58 | * |
59 | */ |
60 | |
61 | struct ipc_importance_elem { |
62 | uint32_t iie_bits; /* type and refs */ |
63 | mach_voucher_attr_value_reference_t iie_made; /* references given to vouchers */ |
64 | queue_head_t iie_kmsgs; /* list of kmsgs inheriting from this */ |
65 | uint32_t iie_externcnt; /* number of externalized boosts */ |
66 | uint32_t iie_externdrop; /* number of those dropped already */ |
67 | #define IIE_REF_DEBUG 0 |
68 | #if IIE_REF_DEBUG |
69 | uint32_t iie_refs_added; /* all refs added via all means */ |
70 | uint32_t iie_refs_dropped; /* all refs dropped via all means */ |
71 | uint32_t iie_kmsg_refs_added; /* all refs added by kmsgs taking a ref */ |
72 | uint32_t iie_kmsg_refs_inherited; /* kmsg refs consumed by a new inherit */ |
73 | uint32_t iie_kmsg_refs_coalesced; /* kmsg refs coalesced into an existing inherit */ |
74 | uint32_t iie_kmsg_refs_dropped; /* kmsg refs dropped by not accepting msg importance */ |
75 | uint32_t iie_task_refs_added; /* refs added by a task reference call */ |
76 | uint32_t iie_task_refs_added_inherit_from; /* task references added by inherit from */ |
77 | uint32_t iie_task_refs_added_transition; /* task references added by imp transition code */ |
78 | uint32_t iie_task_refs_self_added; /* task refs added by self-boost */ |
79 | uint32_t iie_task_refs_inherited; /* task refs consumed by a new inherit */ |
80 | uint32_t iie_task_refs_coalesced; /* task refs coalesced into an existing inherit */ |
81 | uint32_t iie_task_refs_dropped; /* all refs dropped via all task means */ |
82 | #endif |
83 | }; |
84 | |
85 | #define IIE_TYPE_MASK 0x80000000 /* Just the high bit for now */ |
86 | #define IIE_TYPE_TASK 0x00000000 /* Element is a task element */ |
87 | #define IIE_TYPE_INHERIT 0x80000000 /* Element inherits from a previous element */ |
88 | #define IIE_TYPE(e) ((e)->iie_bits & IIE_TYPE_MASK) |
89 | |
90 | #define IIE_REFS_MASK 0x7FFFFFFF /* Mask to extract references */ |
91 | #define IIE_REFS_MAX 0x7FFFFFFF |
92 | #define IIE_REFS(e) ((e)->iie_bits & IIE_REFS_MASK) |
93 | |
94 | #define IIE_EXTERN(e) ((e)->iie_externcnt - (e)->iie_externdrop) |
95 | |
96 | #if !IIE_REF_DEBUG |
97 | #define ipc_importance_reference_internal(elem) \ |
98 | (hw_atomic_add(&(elem)->iie_bits, 1) & IIE_REFS_MASK) |
99 | |
100 | #define ipc_importance_release_internal(elem) \ |
101 | (hw_atomic_sub(&(elem)->iie_bits, 1) & IIE_REFS_MASK) |
102 | #endif |
103 | |
104 | struct ipc_importance_task { |
105 | struct ipc_importance_elem iit_elem; /* common element parts */ |
106 | task_t iit_task; /* task associated with */ |
107 | queue_head_t iit_inherits; /* list of inherit elems hung off this */ |
108 | queue_t iit_updateq; /* queue chained on for task policy updates */ |
109 | queue_chain_t iit_updates; /* link on update chain */ |
110 | queue_chain_t iit_props; /* link on propagation chain */ |
111 | uint64_t iit_updatetime; /* timestamp of our last policy update request */ |
112 | uint64_t iit_transitions;/* total number of boost transitions (lifetime) */ |
113 | uint32_t iit_assertcnt; /* net number of boost assertions (internal, external and legacy) */ |
114 | uint32_t iit_legacy_externcnt; /* Legacy external boost count */ |
115 | uint32_t iit_legacy_externdrop; /* Legacy external boost drop count */ |
116 | uint32_t iit_receiver:1, /* the task can receive importance boost */ |
117 | iit_denap:1, /* the task can be awaked from App Nap */ |
118 | iit_donor:1, /* the task always sends boosts regardless of boost status */ |
119 | iit_live_donor:1, /* the task temporarily sends boosts regardless of boost status */ |
120 | iit_updatepolicy:1, /* enqueue for policy update at the end of propagation */ |
121 | iit_reserved:3, /* reserved for future use */ |
122 | iit_filelocks:24; /* number of file lock boosts */ |
123 | #if DEVELOPMENT || DEBUG |
124 | char iit_procname[20]; /* name of proc */ |
125 | uint32_t iit_bsd_pid; /* pid of proc creating this iit */ |
126 | queue_chain_t iit_allocation; /* link on global iit allocation chain */ |
127 | #endif |
128 | |
129 | }; |
130 | #define iit_bits iit_elem.iie_bits |
131 | #define iit_made iit_elem.iie_made |
132 | #define iit_kmsgs iit_elem.iie_kmsgs |
133 | #define iit_externcnt iit_elem.iie_externcnt |
134 | #define iit_externdrop iit_elem.iie_externdrop |
135 | |
136 | #define IIT_REFS_MAX IIE_REFS_MAX |
137 | #define IIT_REFS(t) IIE_REFS(&(t)->iit_elem) |
138 | #define IIT_EXTERN(t) IIE_EXTERN(&(t)->iit_elem) |
139 | #define IIT_LEGACY_EXTERN(t) ((t)->iit_legacy_externcnt - (t)->iit_legacy_externdrop) |
140 | |
141 | #if !IIE_REF_DEBUG |
142 | #define ipc_importance_task_reference_internal(task_imp) \ |
143 | (ipc_importance_reference_internal(&(task_imp)->iit_elem)) |
144 | |
145 | #define ipc_importance_task_release_internal(task_imp) \ |
146 | (assert(1 < IIT_REFS(task_imp)), ipc_importance_release_internal(&(task_imp)->iit_elem)) |
147 | #endif |
148 | |
149 | typedef int iit_update_type_t; |
150 | #define IIT_UPDATE_HOLD ((iit_update_type_t)1) |
151 | #define IIT_UPDATE_DROP ((iit_update_type_t)2) |
152 | |
153 | struct ipc_importance_inherit { |
154 | struct ipc_importance_elem iii_elem; /* common element partss */ |
155 | boolean_t iii_donating; /* is this donating importance */ |
156 | uint32_t iii_depth; /* nesting depth */ |
157 | ipc_importance_task_t iii_to_task; /* donating to */ |
158 | ipc_importance_elem_t iii_from_elem; /* other elem contributing */ |
159 | queue_chain_t iii_inheritance; /* inherited from link */ |
160 | }; |
161 | #define iii_bits iii_elem.iie_bits |
162 | #define iii_made iii_elem.iie_made |
163 | #define iii_kmsgs iii_elem.iie_kmsgs |
164 | #define iii_externcnt iii_elem.iie_externcnt |
165 | #define iii_externdrop iii_elem.iie_externdrop |
166 | #define III_REFS_MAX IIE_REFS_MAX |
167 | #define III_REFS(i) IIE_REFS(&(i)->iii_elem) |
168 | #define III_EXTERN(i) IIE_EXTERN(&(i)->iii_elem) |
169 | |
170 | #define III_DEPTH_RESET 0x80000000 |
171 | #define III_DEPTH_MASK 0x000000FF |
172 | #define III_DEPTH(i) ((i)->iii_depth & III_DEPTH_MASK) |
173 | #define III_DEPTH_MAX 32 /* maximum inherit->inherit chain depth */ |
174 | |
175 | #define ipc_importance_inherit_reference_internal(inherit) \ |
176 | (ipc_importance_reference_internal(&(inherit)->iii_elem)) |
177 | |
178 | __BEGIN_DECLS |
179 | |
180 | /* add a reference to an importance attribute */ |
181 | extern void ipc_importance_reference(ipc_importance_elem_t elem); |
182 | |
183 | /* release an importance attribute reference */ |
184 | extern void ipc_importance_release(ipc_importance_elem_t elem); |
185 | |
186 | /* retain a task importance attribute reference */ |
187 | extern void ipc_importance_task_reference(ipc_importance_task_t task_elem); |
188 | |
189 | /* release a task importance attribute reference */ |
190 | extern void ipc_importance_task_release(ipc_importance_task_t task_imp); |
191 | |
192 | /* reset the influence of the task on the importance */ |
193 | extern void ipc_importance_reset(ipc_importance_task_t task_imp, boolean_t donor); |
194 | |
195 | extern ipc_importance_task_t ipc_importance_for_task(task_t task, boolean_t made); |
196 | extern void ipc_importance_disconnect_task(task_t task); |
197 | extern ipc_importance_inherit_t ipc_importance_exec_switch_task(task_t old_task, task_t new_task); |
198 | |
199 | extern boolean_t ipc_importance_task_is_donor(ipc_importance_task_t task_imp); |
200 | extern boolean_t ipc_importance_task_is_never_donor(ipc_importance_task_t task_imp); |
201 | extern boolean_t ipc_importance_task_is_marked_donor(ipc_importance_task_t task_imp); |
202 | extern boolean_t ipc_importance_task_is_marked_live_donor(ipc_importance_task_t task_imp); |
203 | |
204 | extern void ipc_importance_task_mark_donor(ipc_importance_task_t task_imp, boolean_t donating); |
205 | extern void ipc_importance_task_mark_live_donor(ipc_importance_task_t task_imp, boolean_t live_donating); |
206 | extern void ipc_importance_task_update_live_donor(ipc_importance_task_t task_imp); |
207 | |
208 | extern boolean_t ipc_importance_task_is_marked_receiver(ipc_importance_task_t task_imp); |
209 | extern void ipc_importance_task_mark_receiver(ipc_importance_task_t task_imp, boolean_t receiving); |
210 | |
211 | extern boolean_t ipc_importance_task_is_denap_receiver(ipc_importance_task_t task_imp); |
212 | extern boolean_t ipc_importance_task_is_marked_denap_receiver(ipc_importance_task_t task_imp); |
213 | extern void ipc_importance_task_mark_denap_receiver(ipc_importance_task_t task_imp, boolean_t receiving); |
214 | |
215 | extern boolean_t ipc_importance_task_is_any_receiver_type(ipc_importance_task_t task_imp); |
216 | |
217 | extern kern_return_t ipc_importance_task_hold_internal_assertion(ipc_importance_task_t task_imp, uint32_t count); |
218 | extern kern_return_t ipc_importance_task_drop_internal_assertion(ipc_importance_task_t task_imp, uint32_t count); |
219 | |
220 | extern kern_return_t ipc_importance_task_hold_file_lock_assertion(ipc_importance_task_t task_imp, uint32_t count); |
221 | extern kern_return_t ipc_importance_task_drop_file_lock_assertion(ipc_importance_task_t task_imp, uint32_t count); |
222 | |
223 | extern kern_return_t ipc_importance_task_hold_legacy_external_assertion(ipc_importance_task_t task_imp, uint32_t count); |
224 | extern kern_return_t ipc_importance_task_drop_legacy_external_assertion(ipc_importance_task_t task_imp, uint32_t count); |
225 | |
226 | extern boolean_t ipc_importance_check_circularity(ipc_port_t port, ipc_port_t dest); |
227 | |
228 | /* prepare importance attributes for sending */ |
229 | extern boolean_t ipc_importance_send( |
230 | ipc_kmsg_t kmsg, |
231 | mach_msg_option_t option); |
232 | |
233 | /* receive importance attributes from message */ |
234 | extern void ipc_importance_receive( |
235 | ipc_kmsg_t kmsg, |
236 | mach_msg_option_t option); |
237 | |
238 | /* undo receive of importance attributes from message */ |
239 | extern void ipc_importance_unreceive( |
240 | ipc_kmsg_t kmsg, |
241 | mach_msg_option_t option); |
242 | |
243 | /* clean importance attributes out of destroyed message */ |
244 | extern void ipc_importance_clean(ipc_kmsg_t kmsg); |
245 | |
246 | /* assert a message is clean w.r.t. importance attributes */ |
247 | extern void ipc_importance_assert_clean(ipc_kmsg_t kmsg); |
248 | |
249 | /* initialize the ipc importance subsystem */ |
250 | extern void ipc_importance_init(void); |
251 | |
252 | /* initialize the ipc importance delayed calls */ |
253 | extern void ipc_importance_thread_call_init(void); |
254 | |
255 | #if DEVELOPMENT || DEBUG |
256 | extern void task_importance_update_owner_info(task_t task); |
257 | #endif |
258 | |
259 | #if XNU_KERNEL_PRIVATE |
260 | #define TASK_IMP_LIST_DONATING_PIDS 0x1 |
261 | extern int task_importance_list_pids(task_t task, int flags, char *pid_list, unsigned int max_count); |
262 | #endif |
263 | |
264 | __END_DECLS |
265 | |
266 | #endif /* MACH_KERNEL_PRIVATE */ |
267 | |
268 | #endif /* _IPC_IPC_IMPORTANCE_H_ */ |
269 | |