osfmk/kern/policy_internal.h

   1 /*
   2  * Copyright (c) 2015-2016 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 _KERN_POLICY_INTERNAL_H_
  30 #define _KERN_POLICY_INTERNAL_H_
  31
  32 /*
  33  * Interfaces for functionality implemented in task_ or thread_policy subsystem
  34  */
  35
  36 #ifdef XNU_KERNEL_PRIVATE
  37
  38 #include <sys/cdefs.h>
  39 #include <mach/kern_return.h>
  40 #include <kern/kern_types.h>
  41 #include <mach/task_policy.h>
  42 #include <kern/task.h>
  43 #include <kern/ledger.h>
  44
  45 /*
  46  ******************************
  47  * XNU-internal functionality
  48  ******************************
  49  */
  50
  51 /*
  52  * Get effective policy
  53  * Only for use by relevant subsystem, should never be passed into a setter!
  54  */
  55 extern int proc_get_effective_task_policy(task_t task, int flavor);
  56 extern int proc_get_effective_thread_policy(thread_t thread, int flavor);
  57
  58 /* Set task 'nice' value */
  59 extern kern_return_t task_importance(task_t task, integer_t importance);
  60
  61 /* value */
  62 #define TASK_POLICY_DISABLE             0x0
  63 #define TASK_POLICY_ENABLE              0x1
  64
  65 /* category */
  66 #define TASK_POLICY_INTERNAL            0x0
  67 #define TASK_POLICY_EXTERNAL            0x1
  68 #define TASK_POLICY_ATTRIBUTE           0x2
  69
  70 /* for tracing */
  71 #define TASK_POLICY_TASK                0x4
  72 #define TASK_POLICY_THREAD              0x8
  73
  74 /* flavors (also DBG_IMPORTANCE subclasses  0x20 - 0x3F) */
  75
  76 /* internal or external, thread or task */
  77 #define TASK_POLICY_DARWIN_BG           0x21
  78 #define TASK_POLICY_IOPOL               0x22
  79 #define TASK_POLICY_IO                  0x23
  80 #define TASK_POLICY_PASSIVE_IO          0x24
  81
  82 /* internal, task only */
  83 #define TASK_POLICY_DARWIN_BG_IOPOL     0x27
  84
  85 /* task-only attributes */
  86 #define TASK_POLICY_TAL                 0x28
  87 #define TASK_POLICY_BOOST               0x29
  88 #define TASK_POLICY_ROLE                0x2A
  89 /* unused                               0x2B */
  90 #define TASK_POLICY_TERMINATED          0x2C
  91 #define TASK_POLICY_NEW_SOCKETS_BG      0x2D
  92 /* unused                               0x2E */
  93 #define TASK_POLICY_LATENCY_QOS         0x2F
  94 #define TASK_POLICY_THROUGH_QOS         0x30
  95 #define TASK_POLICY_WATCHERS_BG         0x31
  96
  97 #define TASK_POLICY_SFI_MANAGED         0x34
  98 #define TASK_POLICY_ALL_SOCKETS_BG      0x37
  99
 100 #define TASK_POLICY_BASE_LATENCY_AND_THROUGHPUT_QOS  0x39 /* latency as value1, throughput as value2 */
 101 #define TASK_POLICY_OVERRIDE_LATENCY_AND_THROUGHPUT_QOS  0x3A /* latency as value1, throughput as value2 */
 102
 103 /* thread-only attributes */
 104 #define TASK_POLICY_PIDBIND_BG          0x32
 105 /* unused                               0x33 */
 106 #define TASK_POLICY_QOS                 0x35
 107 #define TASK_POLICY_QOS_OVERRIDE        0x36
 108 #define TASK_POLICY_QOS_AND_RELPRIO     0x38 /* QoS as value1, relative priority as value2 */
 109 #define TASK_POLICY_QOS_PROMOTE         0x3C
 110 #define TASK_POLICY_QOS_IPC_OVERRIDE    0x3D
 111
 112 #define TASK_POLICY_MAX                 0x3F
 113
 114 /* The main entrance to task policy is this function */
 115 extern void proc_set_task_policy(task_t task, int category, int flavor, int value);
 116 extern int  proc_get_task_policy(task_t task, int category, int flavor);
 117
 118 extern void proc_set_thread_policy(thread_t thread, int category, int flavor, int value);
 119 extern int  proc_get_thread_policy(thread_t thread, int category, int flavor);
 120
 121 /* For use when you don't already hold a reference on the target thread */
 122 extern void proc_set_thread_policy_with_tid(task_t task, uint64_t tid, int category, int flavor, int value);
 123
 124
 125 /* Functions used by kern_resource.c */
 126 extern boolean_t thread_has_qos_policy(thread_t thread);
 127 extern kern_return_t thread_remove_qos_policy(thread_t thread);
 128
 129 extern int  proc_darwin_role_to_task_role(int darwin_role, int* task_role);
 130 extern int  proc_task_role_to_darwin_role(int task_role);
 131
 132 /* Functions used by kern_exec.c */
 133 extern void task_set_main_thread_qos(task_t task, thread_t main_thread);
 134 extern void proc_set_task_spawnpolicy(task_t task, int apptype, int qos_clamp, int role,
 135                                       ipc_port_t * portwatch_ports, int portwatch_count);
 136
 137 /* IO Throttle tiers */
 138 #define THROTTLE_LEVEL_NONE     -1
 139 #define THROTTLE_LEVEL_TIER0     0      /* IOPOL_NORMAL, IOPOL_DEFAULT, IOPOL_PASSIVE */
 140
 141 #define THROTTLE_LEVEL_THROTTLED 1
 142 #define THROTTLE_LEVEL_TIER1     1      /* IOPOL_STANDARD */
 143 #define THROTTLE_LEVEL_TIER2     2      /* IOPOL_UTILITY */
 144 #define THROTTLE_LEVEL_TIER3     3      /* IOPOL_THROTTLE */
 145
 146 #define THROTTLE_LEVEL_START     0
 147 #define THROTTLE_LEVEL_END       3
 148
 149 #define THROTTLE_LEVEL_COMPRESSOR_TIER0         THROTTLE_LEVEL_TIER0
 150 #define THROTTLE_LEVEL_COMPRESSOR_TIER1         THROTTLE_LEVEL_TIER1
 151 #define THROTTLE_LEVEL_COMPRESSOR_TIER2         THROTTLE_LEVEL_TIER2
 152
 153 #define THROTTLE_LEVEL_PAGEOUT_THROTTLED        THROTTLE_LEVEL_TIER2
 154 #define THROTTLE_LEVEL_PAGEOUT_UNTHROTTLED      THROTTLE_LEVEL_TIER1
 155
 156 #if CONFIG_IOSCHED
 157 #define IOSCHED_METADATA_TIER                   THROTTLE_LEVEL_TIER1
 158 #endif /* CONFIG_IOSCHED */
 159
 160 extern int proc_get_darwinbgstate(task_t task, uint32_t *flagsp);
 161 extern int task_get_apptype(task_t);
 162
 163 #ifdef MACH_BSD
 164 extern void proc_apply_task_networkbg(void * bsd_info, thread_t thread);
 165 #endif /* MACH_BSD */
 166
 167 /* Functions used by pthread_shims.c */
 168 extern boolean_t proc_thread_qos_add_override(task_t task, thread_t thread, uint64_t tid,
 169                                               int override_qos, boolean_t first_override_for_resource,
 170                                               user_addr_t resource, int resource_type);
 171 extern int proc_thread_qos_add_override_check_owner(thread_t thread, int override_qos,
 172                 boolean_t first_override_for_resource, user_addr_t resource, int resource_type,
 173                 user_addr_t user_lock_addr, mach_port_name_t user_lock_owner);
 174 extern boolean_t proc_thread_qos_remove_override(task_t task, thread_t thread, uint64_t tid,
 175                                                  user_addr_t resource, int resource_type);
 176 extern boolean_t proc_thread_qos_reset_override(task_t task, thread_t thread, uint64_t tid,
 177                                                  user_addr_t resource, int resource_type);
 178 extern int proc_thread_qos_squash_override(thread_t thread, user_addr_t resource, int resource_type);
 179
 180 extern kern_return_t
 181 thread_set_workq_qos(thread_t thread, int qos_tier, int relprio);
 182 extern kern_return_t
 183 thread_set_workq_pri(thread_t thread, integer_t priority, integer_t policy);
 184
 185 extern int
 186 task_get_default_manager_qos(task_t task);
 187
 188 extern void proc_thread_qos_deallocate(thread_t thread);
 189
 190 extern int task_clear_cpuusage(task_t task, int cpumon_entitled);
 191
 192
 193 /* Importance inheritance functions not under IMPORTANCE_INHERITANCE */
 194 extern void task_importance_mark_donor(task_t task, boolean_t donating);
 195 extern void task_importance_reset(task_t task);
 196
 197 #if IMPORTANCE_INHERITANCE
 198 extern boolean_t task_is_importance_donor(task_t task);
 199 extern boolean_t task_is_importance_receiver_type(task_t task);
 200
 201 extern int task_importance_hold_file_lock_assertion(task_t target_task, uint32_t count);
 202 extern int task_importance_drop_file_lock_assertion(task_t target_task, uint32_t count);
 203
 204 extern int task_importance_hold_legacy_external_assertion(task_t target_task, uint32_t count);
 205 extern int task_importance_drop_legacy_external_assertion(task_t target_task, uint32_t count);
 206 #endif /* IMPORTANCE_INHERITANCE */
 207
 208 /* Functions used by process_policy.c */
 209 extern boolean_t proc_task_is_tal(task_t task);
 210
 211 /* Arguments to proc_set_task_ruse_cpu */
 212 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NONE             0x00
 213 #define TASK_POLICY_RESOURCE_ATTRIBUTE_THROTTLE         0x01
 214 #define TASK_POLICY_RESOURCE_ATTRIBUTE_SUSPEND          0x02
 215 #define TASK_POLICY_RESOURCE_ATTRIBUTE_TERMINATE        0x03
 216 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NOTIFY_KQ        0x04
 217 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NOTIFY_EXC       0x05
 218 #define TASK_POLICY_RESOURCE_ATTRIBUTE_DEFAULT          TASK_POLICY_RESOURCE_ATTRIBUTE_NONE
 219
 220 extern int proc_get_task_ruse_cpu(task_t task, uint32_t *policyp, uint8_t *percentagep,
 221                                   uint64_t *intervalp, uint64_t *deadlinep);
 222 extern int proc_set_task_ruse_cpu(task_t task, uint32_t policy, uint8_t percentage,
 223                                   uint64_t interval, uint64_t deadline, int cpumon_entitled);
 224 extern int task_suspend_cpumon(task_t task);
 225 extern int task_resume_cpumon(task_t task);
 226 extern int proc_clear_task_ruse_cpu(task_t task, int cpumon_entitled);
 227
 228 extern int proc_apply_resource_actions(void * p, int type, int action);
 229 extern int proc_restore_resource_actions(void * p, int type, int action);
 230
 231 /* VM/Jetsam importance callouts */
 232 extern int task_low_mem_privileged_listener(task_t task, boolean_t new_value, boolean_t *old_value);
 233 extern boolean_t task_has_been_notified(task_t task, int pressurelevel);
 234 extern boolean_t task_used_for_purging(task_t task, int pressurelevel);
 235 extern void task_mark_has_been_notified(task_t task, int pressurelevel);
 236 extern void task_mark_used_for_purging(task_t task, int pressurelevel);
 237 extern void task_clear_has_been_notified(task_t task, int pressurelevel);
 238 extern void task_clear_used_for_purging(task_t task);
 239 extern int task_importance_estimate(task_t task);
 240
 241 /*
 242  * Allocate/assign a single work interval ID for a thread,
 243  * and support deallocating it.
 244  */
 245 extern kern_return_t thread_policy_create_work_interval(thread_t thread, uint64_t *work_interval_id);
 246 extern kern_return_t thread_policy_destroy_work_interval(thread_t thread, uint64_t work_interval_id);
 247
 248 extern kern_return_t thread_policy_set_internal(thread_t thread, thread_policy_flavor_t flavor,
 249                                                 thread_policy_t policy_info, mach_msg_type_number_t count);
 250
 251 struct promote_token {
 252         uint16_t        pt_basepri;
 253         uint16_t        pt_qos;
 254 };
 255
 256 #define PROMOTE_TOKEN_INIT ((struct promote_token){.pt_basepri = 0, .pt_qos = 0})
 257
 258 extern void thread_user_promotion_add(thread_t thread, thread_t promoter, struct promote_token* promote_token);
 259 extern void thread_user_promotion_update(thread_t thread, thread_t promoter, struct promote_token* promote_token);
 260 extern void thread_user_promotion_drop(thread_t thread);
 261
 262 /* for IPC override management */
 263 extern void thread_add_ipc_override(thread_t thread, uint32_t qos_override);
 264 extern void thread_update_ipc_override(thread_t thread, uint32_t qos_override);
 265 extern void thread_drop_ipc_override(thread_t thread);
 266 extern uint32_t thread_get_ipc_override(thread_t thread);
 267
 268 /*
 269  ******************************
 270  * Mach-internal functionality
 271  ******************************
 272  */
 273
 274 #ifdef MACH_KERNEL_PRIVATE
 275
 276 /*
 277  * this exports the internal policy update calls
 278  * for IPC importance hooks into task policy
 279  */
 280
 281 typedef struct task_pend_token {
 282         uint32_t        tpt_update_sockets      :1,
 283                         tpt_update_timers       :1,
 284                         tpt_update_watchers     :1,
 285                         tpt_update_live_donor   :1,
 286                         tpt_update_coal_sfi     :1,
 287                         tpt_update_throttle     :1,
 288                         tpt_update_thread_sfi   :1,
 289                         tpt_force_recompute_pri :1;
 290 } *task_pend_token_t;
 291
 292 extern void task_policy_update_complete_unlocked(task_t task, task_pend_token_t pend_token);
 293 extern void task_update_boost_locked(task_t task, boolean_t boost_active, task_pend_token_t pend_token);
 294
 295 extern void thread_policy_update_locked(thread_t thread, task_pend_token_t pend_token);
 296 extern void thread_policy_update_complete_unlocked(thread_t task, task_pend_token_t pend_token);
 297
 298 typedef struct {
 299         int             qos_pri[THREAD_QOS_LAST];
 300         int             qos_iotier[THREAD_QOS_LAST];
 301         uint32_t        qos_through_qos[THREAD_QOS_LAST];
 302         uint32_t        qos_latency_qos[THREAD_QOS_LAST];
 303 } qos_policy_params_t;
 304
 305 extern const qos_policy_params_t thread_qos_policy_params;
 306
 307 /* for task policy tracepoints */
 308 /* Convenience functions for munging a policy bitfield into a tracepoint */
 309 uintptr_t threquested_0(thread_t thread);
 310 uintptr_t threquested_1(thread_t thread);
 311 uintptr_t theffective_0(thread_t thread);
 312 uintptr_t theffective_1(thread_t thread);
 313 extern uint32_t  tpending(task_pend_token_t pend_token);
 314
 315 extern void proc_iopol_to_tier(int iopolicy, int *tier, int *passive);
 316 extern int  proc_tier_to_iopol(int tier, int passive);
 317
 318 extern void set_thread_iotier_override(thread_t, int policy);
 319
 320 extern integer_t task_grab_latency_qos(task_t task);
 321 extern void task_policy_create(task_t task, task_t parent_task);
 322 extern void thread_policy_create(thread_t thread);
 323
 324 extern boolean_t task_is_daemon(task_t task);
 325 extern boolean_t task_is_app(task_t task);
 326
 327
 328 #if IMPORTANCE_INHERITANCE
 329 extern boolean_t task_is_marked_importance_donor(task_t task);
 330 extern boolean_t task_is_marked_importance_receiver(task_t task);
 331
 332 extern boolean_t task_is_marked_importance_denap_receiver(task_t task);
 333 #endif /* IMPORTANCE_INHERITANCE */
 334
 335 /* flags for rusage_cpu_flags */
 336 #define TASK_RUSECPU_FLAGS_PROC_LIMIT                   0x01
 337 #define TASK_RUSECPU_FLAGS_PERTHR_LIMIT                 0x02
 338 #define TASK_RUSECPU_FLAGS_DEADLINE                     0x04
 339 #define TASK_RUSECPU_FLAGS_FATAL_CPUMON                 0x08    /* CPU usage monitor violations are fatal */
 340 #define TASK_RUSECPU_FLAGS_FATAL_WAKEUPSMON             0x10    /* wakeups monitor violations are fatal */
 341 #define TASK_RUSECPU_FLAGS_PHYS_FOOTPRINT_EXCEPTION     0x20    /* exceeding physical footprint generates EXC_RESOURCE */
 342
 343 extern void proc_init_cpumon_params(void);
 344 extern void thread_policy_init(void);
 345
 346 int task_compute_main_thread_qos(task_t task);
 347
 348 /* thread policy internals */
 349 extern void thread_policy_reset(thread_t thread);
 350 extern kern_return_t thread_set_mode_and_absolute_pri(thread_t thread, integer_t policy, integer_t priority);
 351
 352 extern void thread_policy_update_tasklocked(thread_t thread, integer_t priority, integer_t max_priority, task_pend_token_t pend_token);
 353
 354 #include "mach/resource_notify.h"       /* from MIG */
 355
 356 /*! @function   send_resource_violation
 357     @abstract   send usage monitor violation notification
 358
 359     @param  violator  the task (process) violating its CPU budget
 360     @param  ledger_info   the entry tracking the resource limit
 361     @param  flags   see constants for type in sys/reason.h
 362
 363     @result KERN_SUCCESS if the message was sent
 364
 365     @discussion
 366         send_resource_violation() calls the corresponding MIG routine
 367         over the host special RESOURCE_NOTIFY port.
 368 */
 369 kern_return_t send_resource_violation(typeof(send_cpu_usage_violation),
 370                                       task_t violator,
 371                                       struct ledger_entry_info *ledger_info,
 372                                       resource_notify_flags_t flags);
 373
 374 /*! @function   trace_resource_violation
 375     @abstract   trace violations on K32/64
 376
 377     @param  code   the (K64) DBG_MACH_RESOURCE trace code
 378     @param  ledger_info   the entry tracking the resource limit
 379
 380     @discussion
 381         Trace observed usage and corresponding limit on K32 or K64.  On
 382         K32, a pair of trace points are used.  The low nibble of the K32
 383         trace points must start at double the low nibble of the provided
 384         K64 trace point.  For example:
 385                 #define LOGWRITES_VIOLATED              0x022
 386                 ...
 387                 #define LOGWRITES_VIOLATED_K32A         0x024
 388                 #define LOGWRITES_VIOLATED_K32B         0x025
 389 */
 390 void trace_resource_violation(uint16_t code,
 391                               struct ledger_entry_info *ledger_info);
 392
 393 #endif /* MACH_KERNEL_PRIVATE */
 394
 395 #endif /* XNU_KERNEL_PRIVATE */
 396
 397 #endif /* _KERN_POLICY_INTERNAL_H_ */