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