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