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);
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 */
62uint64_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 */
85extern 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 */
107extern 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 */
121extern 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 */
133extern 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 */
146extern 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 */
188extern 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 */
192static inline uint64_t coalition_id(__unused coalition_t coal)
193{
194 return 0;
195}
196
197static 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
204static 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
212static inline int coalition_get_task_count(__unused coalition_t coal)
213{
214 return 0;
215}
216
217static inline uint64_t coalition_get_page_count(__unused coalition_t coal,
218 __unused int *ntasks)
219{
220 return 0;
221}
222
223static 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