1 | /* |
2 | * Copyright (c) 2013 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 _SYS_COALITION_H_ |
30 | #define _SYS_COALITION_H_ |
31 | |
32 | #include <stdint.h> |
33 | #include <sys/cdefs.h> |
34 | #include <sys/types.h> |
35 | |
36 | #include <mach/coalition.h> |
37 | |
38 | __BEGIN_DECLS |
39 | |
40 | #ifndef KERNEL |
41 | /* Userspace syscall prototypes */ |
42 | |
43 | /* Syscalls */ |
44 | int coalition_create(uint64_t *cid_out, uint32_t flags); |
45 | int coalition_terminate(uint64_t cid, uint32_t flags); |
46 | int coalition_reap(uint64_t cid, uint32_t flags); |
47 | |
48 | /* Wrappers around __coalition_info syscall (with proper struct types) */ |
49 | int coalition_info_resource_usage(uint64_t cid, struct coalition_resource_usage *cru, size_t sz); |
50 | int coalition_info_set_name(uint64_t cid, const char *name, size_t size); |
51 | int coalition_info_set_efficiency(uint64_t cid, uint64_t flags); |
52 | int coalition_ledger_set_logical_writes_limit(uint64_t cid, int64_t limit); |
53 | |
54 | #ifdef PRIVATE |
55 | int coalition_info_debug_info(uint64_t cid, struct coalinfo_debuginfo *cru, size_t sz); |
56 | #endif /* PRIVATE */ |
57 | |
58 | #else /* KERNEL */ |
59 | |
60 | #if CONFIG_COALITIONS |
61 | /* in-kernel BSD interfaces */ |
62 | |
63 | /* |
64 | * coalition_id: |
65 | * Get the unique 64-bit identifier associated with the given coalition |
66 | */ |
67 | uint64_t coalition_id(coalition_t coal); |
68 | |
69 | |
70 | /* |
71 | * coalitions_get_list: |
72 | * Get a list of coalitions as procinfo_coalinfo structures |
73 | * |
74 | * This interface is primarily to support libproc. |
75 | * |
76 | * Parameters: |
77 | * type : The COALITION_TYPE of the coalitions to investigate. |
78 | * Valid types can be found in <mach/coalition.h> |
79 | * coal_list : Pointer to an array of procinfo_coalinfo structures |
80 | * that will be filled with information about each |
81 | * coalition whose type matches 'type' |
82 | * NOTE: This can be NULL to perform a simple query of |
83 | * the total number of coalitions. |
84 | * list_sz : The size (in number of structures) of 'coal_list' |
85 | * |
86 | * Returns: 0 if no coalitions matching 'type' are found |
87 | * Otherwise: the number of coalitions whose type matches |
88 | * the 'type' parameter (all coalitions if type == -1) |
89 | */ |
90 | extern size_t coalitions_get_list(int type, struct procinfo_coalinfo *coal_list, size_t list_sz); |
91 | |
92 | |
93 | /* |
94 | * task_get_coalition: |
95 | * Return the coalition of a task. |
96 | * |
97 | * Parameters: |
98 | * task : The task to investigate |
99 | * coal_type : The COALITION_TYPE of the coalition to investigate. |
100 | * Valid types can be found in <mach/coalition.h> |
101 | * |
102 | * Returns: valid coalition_t or COALITION_NULL |
103 | */ |
104 | extern coalition_t task_get_coalition(task_t task, int coal_type); |
105 | |
106 | |
107 | /* |
108 | * coalition_is_leader: |
109 | * Determine if a task is a coalition leader. |
110 | * |
111 | * Parameters: |
112 | * task : The task to investigate |
113 | * coal : The coalition to test against. |
114 | * NOTE: This can be COALITION_NULL, in case FALSE is returned. |
115 | * |
116 | * Returns: TRUE if 'task' is the coalition's leader, FALSE otherwise. |
117 | */ |
118 | extern boolean_t coalition_is_leader(task_t task, coalition_t coal); |
119 | |
120 | /* |
121 | * coalition_get_leader: |
122 | * Get a task reference on the leader of a given coalition |
123 | * |
124 | * Parameters: |
125 | * coal : The coalition to investigate |
126 | * |
127 | * Returns: A referenced task pointer of the leader of the given coalition. |
128 | * This could be TASK_NULL if the coalition doesn't have a leader. |
129 | * If the return value is non-null, the caller is responsible to call |
130 | * task_deallocate on the returned value. |
131 | */ |
132 | extern task_t coalition_get_leader(coalition_t coal); |
133 | |
134 | |
135 | /* |
136 | * coalition_get_task_count: |
137 | * Sum up the number of tasks in the given coalition |
138 | * |
139 | * Parameters: |
140 | * coal : The coalition to investigate |
141 | * |
142 | * Returns: The number of tasks in the coalition |
143 | */ |
144 | extern int coalition_get_task_count(coalition_t coal); |
145 | |
146 | /* |
147 | * coalition_get_page_count: |
148 | * Sum up the page count for each task in the coalition specified by 'coal' |
149 | * |
150 | * Parameters: |
151 | * coal : The coalition to investigate |
152 | * ntasks : If non-NULL, this will be filled in with the number of |
153 | * tasks in the coalition. |
154 | * |
155 | * Returns: The sum of all pages used by all members of the coalition |
156 | */ |
157 | extern uint64_t coalition_get_page_count(coalition_t coal, int *ntasks); |
158 | |
159 | /* |
160 | * coalition_get_pid_list: |
161 | * Gather a list of constituent PIDs of tasks within a coalition playing a |
162 | * given role. |
163 | * |
164 | * Parameters: |
165 | * coal : The coalition to investigate |
166 | * rolemask : The set of coalition task roles used to filter the list |
167 | * of PIDs returned in 'pid_list'. Roles can be combined |
168 | * using the COALITION_ROLEMASK_* tokens found in |
169 | * <mach/coalition.h>. Each PID returned is guaranteed to |
170 | * be tagged with one of the task roles specified by this |
171 | * mask. |
172 | * sort_order : The order in which the returned PIDs should be sorted |
173 | * by default this is in descending page count. |
174 | * pid_list : Pointer to an array of PIDs that will be filled with |
175 | * members of the coalition tagged with the given 'taskrole' |
176 | * list_sz : The size (in number of PIDs) of 'pid_list' |
177 | * |
178 | * Note: |
179 | * This function will return the list of PIDs in a sorted order. By default |
180 | * the PIDs will be sorted by task page count in descending order. In the |
181 | * future it may be possible for user space to specify a level of importance |
182 | * for each coalition member. If there is a user space specified importance, |
183 | * then the list of PIDs returned will be sorted in _ascending_ importance, |
184 | * i.e., pid_list[0] will be the least important task (or the largest consumer |
185 | * of memory). The desired sort order can be specified using the |
186 | * COALITION_SORT_* definitions in osfmk/mach/coalition.h |
187 | * |
188 | * It is also possible to return an unsorted list of PIDs using the special |
189 | * sort type 'COALITION_SORT_NOSORT' |
190 | * |
191 | * Returns: < 0 on ERROR |
192 | * 0 if 'coal' contains no tasks whose role is 'taskrole' |
193 | * (or if the coalition is being deallocated) |
194 | * Otherwise: the number of PIDs in the coalition whose role is |
195 | * 'taskrole'. NOTE: This may be larger or smaller than |
196 | * the 'pid_list' array. |
197 | * |
198 | */ |
199 | extern int coalition_get_pid_list(coalition_t coal, uint32_t rolemask, |
200 | int sort_order, int *pid_list, int list_sz); |
201 | |
202 | /* |
203 | * task_coalition_role_for_type; |
204 | * Get the role of the given task within the given type of coalition. |
205 | * |
206 | * Parameters: |
207 | * task : The task to investigate |
208 | * coalition_type : The coalition type to check |
209 | * |
210 | * Returns: This task's role or COALITION_TASKROLE_NONE. |
211 | */ |
212 | extern int task_coalition_role_for_type(task_t task, int coalition_type); |
213 | #else /* !CONFIG_COALITIONS */ |
214 | static inline uint64_t |
215 | coalition_id(__unused coalition_t coal) |
216 | { |
217 | return 0; |
218 | } |
219 | |
220 | static inline size_t |
221 | coalitions_get_list(__unused int type, |
222 | __unused struct procinfo_coalinfo *coal_list, |
223 | __unused size_t list_sz) |
224 | { |
225 | return 0; |
226 | } |
227 | |
228 | static inline coalition_t |
229 | coalition_get_leader(__unused task_t task, |
230 | __unused int coal_type) |
231 | { |
232 | return COALITION_NULL; |
233 | } |
234 | |
235 | static inline boolean_t |
236 | coalition_is_leader(__unused task_t task, |
237 | __unused coalition_t coal) |
238 | { |
239 | return FALSE; |
240 | } |
241 | |
242 | static inline int |
243 | coalition_get_task_count(__unused coalition_t coal) |
244 | { |
245 | return 0; |
246 | } |
247 | |
248 | static inline uint64_t |
249 | coalition_get_page_count(__unused coalition_t coal, |
250 | __unused int *ntasks) |
251 | { |
252 | return 0; |
253 | } |
254 | |
255 | static inline int |
256 | coalition_get_pid_list(__unused coalition_t coal, |
257 | __unused uint32_t rolemask, |
258 | __unused int sort_order, |
259 | __unused int *pid_list, |
260 | __unused int list_sz) |
261 | { |
262 | return 0; |
263 | } |
264 | #endif |
265 | |
266 | #endif /* KERNEL */ |
267 | |
268 | __END_DECLS |
269 | |
270 | #endif /* _SYS_COALITION_H_ */ |
271 | |