osfmk/ipc/ipc_importance.h

   1 /*
   2  * Copyright (c) 2013 Apple Computer, 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 #ifndef _IPC_IPC_IMPORTANCE_H_
  29 #define _IPC_IPC_IMPORTANCE_H_
  30
  31 #include <mach/mach_types.h>
  32 #include <mach/mach_voucher_types.h>
  33 #include <mach/boolean.h>
  34 #include <ipc/ipc_types.h>
  35 #include <ipc/ipc_voucher.h>
  36
  37 /*
  38  * IPC Importance - All definitions are MACH_KERNEL_PRIVATE
  39  */
  40 #ifdef MACH_KERNEL_PRIVATE
  41
  42 #include <kern/locks.h>
  43 #include <kern/simple_lock.h>
  44
  45 /*
  46  * IPC Importance Value Element
  47  *
  48  * This element represents a single task's (base) importance,
  49  * or in the case of inherited importance, the inheritance
  50  * linkage from the source to the destination task.  In the
  51  * inheritance case, this source can be a base importance or
  52  * another inherited importace.
  53  *
  54  * Whenever the task importance is adjusted, it walks the
  55  * list of IPC-related items it influences (ports and downstream
  56  * tasks doing work on its behalf) and makes adjustments to
  57  * their importance attributes accordingly.
  58  *
  59  */
  60
  61 struct ipc_importance_elem {
  62         uint32_t                                iie_bits;       /* type and refs */
  63         mach_voucher_attr_value_reference_t     iie_made;       /* references given to vouchers */
  64         queue_head_t                            iie_kmsgs;      /* list of kmsgs inheriting from this */
  65         uint32_t                                iie_externcnt;  /* number of externalized boosts */
  66         uint32_t                                iie_externdrop; /* number of those dropped already */
  67 #define IIE_REF_DEBUG 0
  68 #if IIE_REF_DEBUG
  69         uint32_t iie_refs_added;                        /* all refs added via all means */
  70         uint32_t iie_refs_dropped;                      /* all refs dropped via all means */
  71         uint32_t iie_kmsg_refs_added;                   /* all refs added by kmsgs taking a ref */
  72         uint32_t iie_kmsg_refs_inherited;               /* kmsg refs consumed by a new inherit */
  73         uint32_t iie_kmsg_refs_coalesced;               /* kmsg refs coalesced into an existing inherit */
  74         uint32_t iie_kmsg_refs_dropped;                 /* kmsg refs dropped by not accepting msg importance */
  75         uint32_t iie_task_refs_added;                   /* refs added by a task reference call */
  76         uint32_t iie_task_refs_added_inherit_from;      /* task references added by inherit from */
  77         uint32_t iie_task_refs_added_transition;        /* task references added by imp transition code */
  78         uint32_t iie_task_refs_self_added;              /* task refs added by self-boost */
  79         uint32_t iie_task_refs_inherited;               /* task refs consumed by a new inherit */
  80         uint32_t iie_task_refs_coalesced;               /* task refs coalesced into an existing inherit */
  81         uint32_t iie_task_refs_dropped;                 /* all refs dropped via all task means */
  82 #endif
  83 };
  84
  85 #define IIE_TYPE_MASK           0x80000000      /* Just the high bit for now */
  86 #define IIE_TYPE_TASK           0x00000000      /* Element is a task element */
  87 #define IIE_TYPE_INHERIT        0x80000000      /* Element inherits from a previous element */
  88 #define IIE_TYPE(e)             ((e)->iie_bits & IIE_TYPE_MASK)
  89
  90 #define IIE_REFS_MASK           0x7FFFFFFF      /* Mask to extract references */
  91 #define IIE_REFS_MAX            0x7FFFFFFF
  92 #define IIE_REFS(e)             ((e)->iie_bits & IIE_REFS_MASK)
  93
  94 #define IIE_EXTERN(e)           ((e)->iie_externcnt - (e)->iie_externdrop)
  95
  96 #if !IIE_REF_DEBUG
  97 #define ipc_importance_reference_internal(elem)         \
  98         (os_atomic_inc(&(elem)->iie_bits, relaxed) & IIE_REFS_MASK)
  99
 100 #define ipc_importance_release_internal(elem)           \
 101         (os_atomic_dec(&(elem)->iie_bits, relaxed) & IIE_REFS_MASK)
 102 #endif
 103
 104 struct ipc_importance_task {
 105         struct ipc_importance_elem iit_elem;    /* common element parts */
 106         task_t                  iit_task;       /* task associated with */
 107         queue_head_t            iit_inherits;   /* list of inherit elems hung off this */
 108         queue_t                 iit_updateq;    /* queue chained on for task policy updates */
 109         queue_chain_t           iit_updates;    /* link on update chain */
 110         queue_chain_t           iit_props;      /* link on propagation chain */
 111         uint64_t                iit_updatetime; /* timestamp of our last policy update request */
 112         uint64_t                iit_transitions;/* total number of boost transitions (lifetime) */
 113         uint32_t                iit_assertcnt;  /* net number of boost assertions (internal, external and legacy) */
 114         uint32_t                iit_legacy_externcnt;  /* Legacy external boost count */
 115         uint32_t                iit_legacy_externdrop; /* Legacy external boost drop count */
 116         uint32_t                iit_receiver:1, /* the task can receive importance boost */
 117             iit_denap:1,                        /* the task can be awaked from App Nap */
 118             iit_donor:1,                        /* the task always sends boosts regardless of boost status */
 119             iit_live_donor:1,                          /* the task temporarily sends boosts regardless of boost status */
 120             iit_updatepolicy:1,                        /* enqueue for policy update at the end of propagation */
 121             iit_reserved:3,                            /* reserved for future use */
 122             iit_filelocks:24;                          /* number of file lock boosts */
 123 #if DEVELOPMENT || DEBUG
 124         char                    iit_procname[20];      /* name of proc */
 125         uint32_t                iit_bsd_pid;           /* pid of proc creating this iit */
 126         queue_chain_t           iit_allocation;        /* link on global iit allocation chain */
 127 #endif
 128 };
 129 #define iit_bits                iit_elem.iie_bits
 130 #define iit_made                iit_elem.iie_made
 131 #define iit_kmsgs               iit_elem.iie_kmsgs
 132 #define iit_externcnt           iit_elem.iie_externcnt
 133 #define iit_externdrop          iit_elem.iie_externdrop
 134
 135 #define IIT_REFS_MAX            IIE_REFS_MAX
 136 #define IIT_REFS(t)             IIE_REFS(&(t)->iit_elem)
 137 #define IIT_EXTERN(t)           IIE_EXTERN(&(t)->iit_elem)
 138 #define IIT_LEGACY_EXTERN(t)    ((t)->iit_legacy_externcnt - (t)->iit_legacy_externdrop)
 139
 140 #if !IIE_REF_DEBUG
 141 #define ipc_importance_task_reference_internal(task_imp)        \
 142         (ipc_importance_reference_internal(&(task_imp)->iit_elem))
 143
 144 #define ipc_importance_task_release_internal(task_imp)          \
 145         (assert(1 < IIT_REFS(task_imp)), ipc_importance_release_internal(&(task_imp)->iit_elem))
 146 #endif
 147
 148 typedef int iit_update_type_t;
 149 #define IIT_UPDATE_HOLD                 ((iit_update_type_t)1)
 150 #define IIT_UPDATE_DROP                 ((iit_update_type_t)2)
 151
 152 struct ipc_importance_inherit {
 153         struct ipc_importance_elem      iii_elem;         /* common element partss */
 154         boolean_t                       iii_donating;     /* is this donating importance */
 155         uint32_t                        iii_depth;        /* nesting depth */
 156         ipc_importance_task_t           iii_to_task;      /* donating to */
 157         ipc_importance_elem_t           iii_from_elem;    /* other elem contributing */
 158         queue_chain_t                   iii_inheritance;  /* inherited from link */
 159 };
 160 #define iii_bits                        iii_elem.iie_bits
 161 #define iii_made                        iii_elem.iie_made
 162 #define iii_kmsgs                       iii_elem.iie_kmsgs
 163 #define iii_externcnt                   iii_elem.iie_externcnt
 164 #define iii_externdrop                  iii_elem.iie_externdrop
 165 #define III_REFS_MAX                    IIE_REFS_MAX
 166 #define III_REFS(i)                     IIE_REFS(&(i)->iii_elem)
 167 #define III_EXTERN(i)                   IIE_EXTERN(&(i)->iii_elem)
 168
 169 #define III_DEPTH_RESET                 0x80000000
 170 #define III_DEPTH_MASK                  0x000000FF
 171 #define III_DEPTH(i)                    ((i)->iii_depth & III_DEPTH_MASK)
 172 #define III_DEPTH_MAX                   32      /* maximum inherit->inherit chain depth */
 173
 174 #define ipc_importance_inherit_reference_internal(inherit)      \
 175         (ipc_importance_reference_internal(&(inherit)->iii_elem))
 176
 177 __BEGIN_DECLS
 178
 179 /* add a reference to an importance attribute */
 180 extern void ipc_importance_reference(ipc_importance_elem_t elem);
 181
 182 /* release an importance attribute reference */
 183 extern void ipc_importance_release(ipc_importance_elem_t elem);
 184
 185 /* retain a task importance attribute reference */
 186 extern void ipc_importance_task_reference(ipc_importance_task_t task_elem);
 187
 188 /* release a task importance attribute reference */
 189 extern void ipc_importance_task_release(ipc_importance_task_t task_imp);
 190
 191 /* reset the influence of the task on the importance */
 192 extern void ipc_importance_reset(ipc_importance_task_t task_imp, boolean_t donor);
 193
 194 extern ipc_importance_task_t ipc_importance_for_task(task_t task, boolean_t made);
 195 extern void ipc_importance_disconnect_task(task_t task);
 196 extern ipc_importance_inherit_t ipc_importance_exec_switch_task(task_t old_task, task_t new_task);
 197
 198 extern boolean_t ipc_importance_task_is_donor(ipc_importance_task_t task_imp);
 199 extern boolean_t ipc_importance_task_is_never_donor(ipc_importance_task_t task_imp);
 200 extern boolean_t ipc_importance_task_is_marked_donor(ipc_importance_task_t task_imp);
 201 extern boolean_t ipc_importance_task_is_marked_live_donor(ipc_importance_task_t task_imp);
 202
 203 extern void ipc_importance_task_mark_donor(ipc_importance_task_t task_imp, boolean_t donating);
 204 extern void ipc_importance_task_mark_live_donor(ipc_importance_task_t task_imp, boolean_t live_donating);
 205 extern void ipc_importance_task_update_live_donor(ipc_importance_task_t task_imp);
 206
 207 extern boolean_t ipc_importance_task_is_marked_receiver(ipc_importance_task_t task_imp);
 208 extern void ipc_importance_task_mark_receiver(ipc_importance_task_t task_imp, boolean_t receiving);
 209
 210 extern boolean_t ipc_importance_task_is_denap_receiver(ipc_importance_task_t task_imp);
 211 extern boolean_t ipc_importance_task_is_marked_denap_receiver(ipc_importance_task_t task_imp);
 212 extern void ipc_importance_task_mark_denap_receiver(ipc_importance_task_t task_imp, boolean_t receiving);
 213
 214 extern boolean_t ipc_importance_task_is_any_receiver_type(ipc_importance_task_t task_imp);
 215
 216 extern kern_return_t ipc_importance_task_hold_internal_assertion(ipc_importance_task_t task_imp, uint32_t count);
 217 extern kern_return_t ipc_importance_task_drop_internal_assertion(ipc_importance_task_t task_imp, uint32_t count);
 218
 219 extern kern_return_t ipc_importance_task_hold_file_lock_assertion(ipc_importance_task_t task_imp, uint32_t count);
 220 extern kern_return_t ipc_importance_task_drop_file_lock_assertion(ipc_importance_task_t task_imp, uint32_t count);
 221
 222 extern kern_return_t ipc_importance_task_hold_legacy_external_assertion(ipc_importance_task_t task_imp, uint32_t count);
 223 extern kern_return_t ipc_importance_task_drop_legacy_external_assertion(ipc_importance_task_t task_imp, uint32_t count);
 224
 225 extern boolean_t ipc_importance_check_circularity(ipc_port_t port, ipc_port_t dest);
 226
 227 /* prepare importance attributes for sending */
 228 extern boolean_t ipc_importance_send(
 229         ipc_kmsg_t              kmsg,
 230         mach_msg_option_t       option);
 231
 232 /* receive importance attributes from message */
 233 extern void ipc_importance_receive(
 234         ipc_kmsg_t              kmsg,
 235         mach_msg_option_t       option);
 236
 237 /* undo receive of importance attributes from message */
 238 extern void ipc_importance_unreceive(
 239         ipc_kmsg_t              kmsg,
 240         mach_msg_option_t       option);
 241
 242 /* clean importance attributes out of destroyed message */
 243 extern void ipc_importance_clean(ipc_kmsg_t kmsg);
 244
 245 /* assert a message is clean w.r.t. importance attributes */
 246 extern void ipc_importance_assert_clean(ipc_kmsg_t kmsg);
 247
 248 /* initialize the ipc importance subsystem */
 249 extern void ipc_importance_init(void);
 250
 251 /* initialize the ipc importance delayed calls */
 252 extern void ipc_importance_thread_call_init(void);
 253
 254 #if DEVELOPMENT || DEBUG
 255 extern void task_importance_update_owner_info(task_t task);
 256 #endif
 257
 258 #if XNU_KERNEL_PRIVATE
 259 #define TASK_IMP_LIST_DONATING_PIDS  0x1
 260 extern int task_importance_list_pids(task_t task, int flags, char *pid_list, unsigned int max_count);
 261 #endif
 262
 263 __END_DECLS
 264
 265 #endif /* MACH_KERNEL_PRIVATE */
 266
 267 #endif  /* _IPC_IPC_IMPORTANCE_H_ */