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