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