bsd/sys/coalition.h

   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 #else /* !CONFIG_COALITIONS */
 199 static inline uint64_t
 200 coalition_id(__unused coalition_t coal)
 201 {
 202         return 0;
 203 }
 204
 205 static inline int
 206 coalitions_get_list(__unused int type,
 207     __unused struct procinfo_coalinfo *coal_list,
 208     __unused int list_sz)
 209 {
 210         return 0;
 211 }
 212
 213 static inline coalition_t
 214 coalition_get_leader(__unused task_t task,
 215     __unused int coal_type)
 216 {
 217         return COALITION_NULL;
 218 }
 219
 220 static inline boolean_t
 221 coalition_is_leader(__unused task_t task,
 222     __unused coalition_t coal)
 223 {
 224         return FALSE;
 225 }
 226
 227 static inline int
 228 coalition_get_task_count(__unused coalition_t coal)
 229 {
 230         return 0;
 231 }
 232
 233 static inline uint64_t
 234 coalition_get_page_count(__unused coalition_t coal,
 235     __unused int *ntasks)
 236 {
 237         return 0;
 238 }
 239
 240 static inline int
 241 coalition_get_pid_list(__unused coalition_t coal,
 242     __unused uint32_t rolemask,
 243     __unused int sort_order,
 244     __unused int *pid_list,
 245     __unused int list_sz)
 246 {
 247         return 0;
 248 }
 249 #endif
 250
 251 #endif /* KERNEL */
 252
 253 __END_DECLS
 254
 255 #endif /* _SYS_COALITION_H_ */