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