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 */
44int coalition_create(uint64_t *cid_out, uint32_t flags);
45int coalition_terminate(uint64_t cid, uint32_t flags);
46int coalition_reap(uint64_t cid, uint32_t flags);
47
48/* Wrappers around __coalition_info syscall (with proper struct types) */
49int coalition_info_resource_usage(uint64_t cid, struct coalition_resource_usage *cru, size_t sz);
50int coalition_info_set_name(uint64_t cid, const char *name, size_t size);
51int coalition_info_set_efficiency(uint64_t cid, uint64_t flags);
52int coalition_ledger_set_logical_writes_limit(uint64_t cid, int64_t limit);
53
54#ifdef PRIVATE
55int 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 */
67uint64_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 */
90extern 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 */
104extern 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 */
118extern 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 */
132extern 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 */
144extern 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 */
157extern 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 */
199extern 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 */
212extern int task_coalition_role_for_type(task_t task, int coalition_type);
213#else /* !CONFIG_COALITIONS */
214static inline uint64_t
215coalition_id(__unused coalition_t coal)
216{
217 return 0;
218}
219
220static inline size_t
221coalitions_get_list(__unused int type,
222 __unused struct procinfo_coalinfo *coal_list,
223 __unused size_t list_sz)
224{
225 return 0;
226}
227
228static inline coalition_t
229coalition_get_leader(__unused task_t task,
230 __unused int coal_type)
231{
232 return COALITION_NULL;
233}
234
235static inline boolean_t
236coalition_is_leader(__unused task_t task,
237 __unused coalition_t coal)
238{
239 return FALSE;
240}
241
242static inline int
243coalition_get_task_count(__unused coalition_t coal)
244{
245 return 0;
246}
247
248static inline uint64_t
249coalition_get_page_count(__unused coalition_t coal,
250 __unused int *ntasks)
251{
252 return 0;
253}
254
255static inline int
256coalition_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