2 * Copyright (c) 2013 Apple Inc. All rights reserved.
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
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.
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
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.
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
29 #ifndef _SYS_COALITION_H_
30 #define _SYS_COALITION_H_
33 #include <sys/cdefs.h>
34 #include <sys/types.h>
36 #include <mach/coalition.h>
41 /* Userspace syscall prototypes */
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
);
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
);
54 /* in-kernel BSD interfaces */
58 * Get the unique 64-bit identifier associated with the given coalition
60 uint64_t coalition_id(coalition_t coal
);
64 * coalitions_get_list:
65 * Get a list of coalitions as procinfo_coalinfo structures
67 * This interface is primarily to support libproc.
70 * type : The COALITION_TYPE of the coalitions to investigate.
71 * Valid types can be found in <mach/coalition.h>
72 * coal_list : Pointer to an array of procinfo_coalinfo structures
73 * that will be filled with information about each
74 * coalition whose type matches 'type'
75 * NOTE: This can be NULL to perform a simple query of
76 * the total number of coalitions.
77 * list_sz : The size (in number of structures) of 'coal_list'
79 * Returns: 0 if no coalitions matching 'type' are found
80 * Otherwise: the number of coalitions whose type matches
81 * the 'type' parameter (all coalitions if type == -1)
83 extern int coalitions_get_list(int type
, struct procinfo_coalinfo
*coal_list
, int list_sz
);
87 * coalition_is_leader:
88 * Determine if a task is a coalition leader.
91 * task : The task to investigate
92 * coal_type : The COALITION_TYPE of the coalition to investigate.
93 * Valid types can be found in <mach/coalition.h>
94 * coal : If 'task' is a valid task, and is a member of a coalition
95 * of type 'coal_type', then 'coal' will be filled in with
96 * the corresponding coalition_t object.
97 * NOTE: This will be filled in whether or not the 'task' is
98 * a leader in the coalition. However, if 'task' is
99 * not a member of a coalition of type 'coal_type' then
100 * 'coal' will be filled in with COALITION_NULL.
101 * NOTE: This can be NULL
103 * Returns: TRUE if 'task' is a coalition leader, FALSE otherwise.
105 extern boolean_t
coalition_is_leader(task_t task
, int coal_type
, coalition_t
*coal
);
108 * coalition_get_task_count:
109 * Sum up the number of tasks in the given coalition
112 * coal : The coalition to investigate
114 * Returns: The number of tasks in the coalition
116 extern int coalition_get_task_count(coalition_t coal
);
119 * coalition_get_page_count:
120 * Sum up the page count for each task in the coalition specified by 'coal'
123 * coal : The coalition to investigate
124 * ntasks : If non-NULL, this will be filled in with the number of
125 * tasks in the coalition.
127 * Returns: The sum of all pages used by all members of the coalition
129 extern uint64_t coalition_get_page_count(coalition_t coal
, int *ntasks
);
132 * coalition_get_pid_list:
133 * Gather a list of constituent PIDs of tasks within a coalition playing a
137 * coal : The coalition to investigate
138 * rolemask : The set of coalition task roles used to filter the list
139 * of PIDs returned in 'pid_list'. Roles can be combined
140 * using the COALITION_ROLEMASK_* tokens found in
141 * <mach/coalition.h>. Each PID returned is guaranteed to
142 * be tagged with one of the task roles specified by this
144 * sort_order : The order in which the returned PIDs should be sorted
145 * by default this is in descending page count.
146 * pid_list : Pointer to an array of PIDs that will be filled with
147 * members of the coalition tagged with the given 'taskrole'
148 * list_sz : The size (in number of PIDs) of 'pid_list'
151 * This function will return the list of PIDs in a sorted order. By default
152 * the PIDs will be sorted by task page count in descending order. In the
153 * future it may be possible for user space to specify a level of importance
154 * for each coalition member. If there is a user space specified importance,
155 * then the list of PIDs returned will be sorted in _ascending_ importance,
156 * i.e., pid_list[0] will be the least important task (or the largest consumer
157 * of memory). The desired sort order can be specified using the
158 * COALITION_SORT_* definitions in osfmk/mach/coalition.h
160 * It is also possible to return an unsorted list of PIDs using the special
161 * sort type 'COALITION_SORT_NOSORT'
163 * Returns: < 0 on ERROR
164 * 0 if 'coal' contains no tasks whose role is 'taskrole'
165 * (or if the coalition is being deallocated)
166 * Otherwise: the number of PIDs in the coalition whose role is
167 * 'taskrole'. NOTE: This may be larger or smaller than
168 * the 'pid_list' array.
171 extern int coalition_get_pid_list(coalition_t coal
, uint32_t rolemask
,
172 int sort_order
, int *pid_list
, int list_sz
);
174 #else /* !CONFIG_COALITIONS */
175 static inline uint64_t coalition_id(__unused coalition_t coal
)
180 static inline int coalitions_get_list(__unused
int type
,
181 __unused
struct procinfo_coalinfo
*coal_list
,
182 __unused
int list_sz
)
187 static inline boolean_t
coalition_is_leader(__unused task_t task
,
188 __unused
int coal_type
,
191 *coal
= COALITION_NULL
;
195 static inline int coalition_get_task_count(__unused coalition_t coal
)
200 static inline uint64_t coalition_get_page_count(__unused coalition_t coal
,
201 __unused
int *ntasks
)
206 static inline int coalition_get_pid_list(__unused coalition_t coal
,
207 __unused
uint32_t rolemask
,
208 __unused
int sort_order
,
209 __unused
int *pid_list
,
210 __unused
int list_sz
)
220 #endif /* _SYS_COALITION_H_ */