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 | |
53 | #else /* KERNEL */ |
54 | |
55 | #if CONFIG_COALITIONS |
56 | /* in-kernel BSD interfaces */ |
57 | |
58 | /* |
59 | * coalition_id: |
60 | * Get the unique 64-bit identifier associated with the given coalition |
61 | */ |
62 | uint64_t coalition_id(coalition_t coal); |
63 | |
64 | |
65 | /* |
66 | * coalitions_get_list: |
67 | * Get a list of coalitions as procinfo_coalinfo structures |
68 | * |
69 | * This interface is primarily to support libproc. |
70 | * |
71 | * Parameters: |
72 | * type : The COALITION_TYPE of the coalitions to investigate. |
73 | * Valid types can be found in <mach/coalition.h> |
74 | * coal_list : Pointer to an array of procinfo_coalinfo structures |
75 | * that will be filled with information about each |
76 | * coalition whose type matches 'type' |
77 | * NOTE: This can be NULL to perform a simple query of |
78 | * the total number of coalitions. |
79 | * list_sz : The size (in number of structures) of 'coal_list' |
80 | * |
81 | * Returns: 0 if no coalitions matching 'type' are found |
82 | * Otherwise: the number of coalitions whose type matches |
83 | * the 'type' parameter (all coalitions if type == -1) |
84 | */ |
85 | extern int coalitions_get_list(int type, struct procinfo_coalinfo *coal_list, int list_sz); |
86 | |
87 | |
88 | /* |
89 | * coalition_is_leader: |
90 | * Determine if a task is a coalition leader. |
91 | * |
92 | * Parameters: |
93 | * task : The task to investigate |
94 | * coal_type : The COALITION_TYPE of the coalition to investigate. |
95 | * Valid types can be found in <mach/coalition.h> |
96 | * coal : If 'task' is a valid task, and is a member of a coalition |
97 | * of type 'coal_type', then 'coal' will be filled in with |
98 | * the corresponding coalition_t object. |
99 | * NOTE: This will be filled in whether or not the 'task' is |
100 | * a leader in the coalition. However, if 'task' is |
101 | * not a member of a coalition of type 'coal_type' then |
102 | * 'coal' will be filled in with COALITION_NULL. |
103 | * NOTE: This can be NULL |
104 | * |
105 | * Returns: TRUE if 'task' is a coalition leader, FALSE otherwise. |
106 | */ |
107 | extern boolean_t coalition_is_leader(task_t task, int coal_type, coalition_t *coal); |
108 | |
109 | /* |
110 | * coalition_get_leader: |
111 | * Get a task reference on the leader of a given coalition |
112 | * |
113 | * Parameters: |
114 | * coal : The coalition to investigate |
115 | * |
116 | * Returns: A referenced task pointer of the leader of the given coalition. |
117 | * This could be TASK_NULL if the coalition doesn't have a leader. |
118 | * If the return value is non-null, the caller is responsible to call |
119 | * task_deallocate on the returned value. |
120 | */ |
121 | extern task_t coalition_get_leader(coalition_t coal); |
122 | |
123 | |
124 | /* |
125 | * coalition_get_task_count: |
126 | * Sum up the number of tasks in the given coalition |
127 | * |
128 | * Parameters: |
129 | * coal : The coalition to investigate |
130 | * |
131 | * Returns: The number of tasks in the coalition |
132 | */ |
133 | extern int coalition_get_task_count(coalition_t coal); |
134 | |
135 | /* |
136 | * coalition_get_page_count: |
137 | * Sum up the page count for each task in the coalition specified by 'coal' |
138 | * |
139 | * Parameters: |
140 | * coal : The coalition to investigate |
141 | * ntasks : If non-NULL, this will be filled in with the number of |
142 | * tasks in the coalition. |
143 | * |
144 | * Returns: The sum of all pages used by all members of the coalition |
145 | */ |
146 | extern uint64_t coalition_get_page_count(coalition_t coal, int *ntasks); |
147 | |
148 | /* |
149 | * coalition_get_pid_list: |
150 | * Gather a list of constituent PIDs of tasks within a coalition playing a |
151 | * given role. |
152 | * |
153 | * Parameters: |
154 | * coal : The coalition to investigate |
155 | * rolemask : The set of coalition task roles used to filter the list |
156 | * of PIDs returned in 'pid_list'. Roles can be combined |
157 | * using the COALITION_ROLEMASK_* tokens found in |
158 | * <mach/coalition.h>. Each PID returned is guaranteed to |
159 | * be tagged with one of the task roles specified by this |
160 | * mask. |
161 | * sort_order : The order in which the returned PIDs should be sorted |
162 | * by default this is in descending page count. |
163 | * pid_list : Pointer to an array of PIDs that will be filled with |
164 | * members of the coalition tagged with the given 'taskrole' |
165 | * list_sz : The size (in number of PIDs) of 'pid_list' |
166 | * |
167 | * Note: |
168 | * This function will return the list of PIDs in a sorted order. By default |
169 | * the PIDs will be sorted by task page count in descending order. In the |
170 | * future it may be possible for user space to specify a level of importance |
171 | * for each coalition member. If there is a user space specified importance, |
172 | * then the list of PIDs returned will be sorted in _ascending_ importance, |
173 | * i.e., pid_list[0] will be the least important task (or the largest consumer |
174 | * of memory). The desired sort order can be specified using the |
175 | * COALITION_SORT_* definitions in osfmk/mach/coalition.h |
176 | * |
177 | * It is also possible to return an unsorted list of PIDs using the special |
178 | * sort type 'COALITION_SORT_NOSORT' |
179 | * |
180 | * Returns: < 0 on ERROR |
181 | * 0 if 'coal' contains no tasks whose role is 'taskrole' |
182 | * (or if the coalition is being deallocated) |
183 | * Otherwise: the number of PIDs in the coalition whose role is |
184 | * 'taskrole'. NOTE: This may be larger or smaller than |
185 | * the 'pid_list' array. |
186 | * |
187 | */ |
188 | extern int coalition_get_pid_list(coalition_t coal, uint32_t rolemask, |
189 | int sort_order, int *pid_list, int list_sz); |
190 | |
191 | #else /* !CONFIG_COALITIONS */ |
192 | static inline uint64_t coalition_id(__unused coalition_t coal) |
193 | { |
194 | return 0; |
195 | } |
196 | |
197 | static inline int coalitions_get_list(__unused int type, |
198 | __unused struct procinfo_coalinfo *coal_list, |
199 | __unused int list_sz) |
200 | { |
201 | return 0; |
202 | } |
203 | |
204 | static inline boolean_t coalition_is_leader(__unused task_t task, |
205 | __unused int coal_type, |
206 | coalition_t *coal) |
207 | { |
208 | *coal = COALITION_NULL; |
209 | return FALSE; |
210 | } |
211 | |
212 | static inline int coalition_get_task_count(__unused coalition_t coal) |
213 | { |
214 | return 0; |
215 | } |
216 | |
217 | static inline uint64_t coalition_get_page_count(__unused coalition_t coal, |
218 | __unused int *ntasks) |
219 | { |
220 | return 0; |
221 | } |
222 | |
223 | static inline int coalition_get_pid_list(__unused coalition_t coal, |
224 | __unused uint32_t rolemask, |
225 | __unused int sort_order, |
226 | __unused int *pid_list, |
227 | __unused int list_sz) |
228 | { |
229 | return 0; |
230 | } |
231 | #endif |
232 | |
233 | #endif /* KERNEL */ |
234 | |
235 | __END_DECLS |
236 | |
237 | #endif /* _SYS_COALITION_H_ */ |
238 | |