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 extern void proc_inherit_task_role(task_t new_task, task_t old_task);
 137
 138 /* IO Throttle tiers */
 139 #define THROTTLE_LEVEL_NONE     -1
 140 #define THROTTLE_LEVEL_TIER0     0      /* IOPOL_NORMAL, IOPOL_DEFAULT, IOPOL_PASSIVE */
 141
 142 #define THROTTLE_LEVEL_THROTTLED 1
 143 #define THROTTLE_LEVEL_TIER1     1      /* IOPOL_STANDARD */
 144 #define THROTTLE_LEVEL_TIER2     2      /* IOPOL_UTILITY */
 145 #define THROTTLE_LEVEL_TIER3     3      /* IOPOL_THROTTLE */
 146
 147 #define THROTTLE_LEVEL_START     0
 148 #define THROTTLE_LEVEL_END       3
 149
 150 #define THROTTLE_LEVEL_COMPRESSOR_TIER0         THROTTLE_LEVEL_TIER0
 151 #define THROTTLE_LEVEL_COMPRESSOR_TIER1         THROTTLE_LEVEL_TIER1
 152 #define THROTTLE_LEVEL_COMPRESSOR_TIER2         THROTTLE_LEVEL_TIER2
 153
 154 #define THROTTLE_LEVEL_PAGEOUT_THROTTLED        THROTTLE_LEVEL_TIER2
 155 #define THROTTLE_LEVEL_PAGEOUT_UNTHROTTLED      THROTTLE_LEVEL_TIER1
 156
 157 #if CONFIG_IOSCHED
 158 #define IOSCHED_METADATA_TIER                   THROTTLE_LEVEL_TIER1
 159 #endif /* CONFIG_IOSCHED */
 160
 161 extern int proc_get_darwinbgstate(task_t task, uint32_t *flagsp);
 162 extern int task_get_apptype(task_t);
 163
 164 #ifdef MACH_BSD
 165 extern void proc_apply_task_networkbg(void * bsd_info, thread_t thread);
 166 #endif /* MACH_BSD */
 167
 168 /* Functions used by pthread_shims.c */
 169 extern boolean_t proc_thread_qos_add_override(task_t task, thread_t thread, uint64_t tid,
 170                                               int override_qos, boolean_t first_override_for_resource,
 171                                               user_addr_t resource, int resource_type);
 172 extern int proc_thread_qos_add_override_check_owner(thread_t thread, int override_qos,
 173                 boolean_t first_override_for_resource, user_addr_t resource, int resource_type,
 174                 user_addr_t user_lock_addr, mach_port_name_t user_lock_owner);
 175 extern boolean_t proc_thread_qos_remove_override(task_t task, thread_t thread, uint64_t tid,
 176                                                  user_addr_t resource, int resource_type);
 177 extern boolean_t proc_thread_qos_reset_override(task_t task, thread_t thread, uint64_t tid,
 178                                                  user_addr_t resource, int resource_type);
 179 extern int proc_thread_qos_squash_override(thread_t thread, user_addr_t resource, int resource_type);
 180
 181 extern kern_return_t
 182 thread_set_workq_qos(thread_t thread, int qos_tier, int relprio);
 183 extern kern_return_t
 184 thread_set_workq_pri(thread_t thread, integer_t priority, integer_t policy);
 185
 186 extern int
 187 task_get_default_manager_qos(task_t task);
 188
 189 extern void proc_thread_qos_deallocate(thread_t thread);
 190
 191 extern int task_clear_cpuusage(task_t task, int cpumon_entitled);
 192
 193
 194 /* Importance inheritance functions not under IMPORTANCE_INHERITANCE */
 195 extern void task_importance_mark_donor(task_t task, boolean_t donating);
 196 extern void task_importance_reset(task_t task);
 197
 198 #if IMPORTANCE_INHERITANCE
 199 extern boolean_t task_is_importance_donor(task_t task);
 200 extern boolean_t task_is_importance_receiver_type(task_t task);
 201
 202 extern int task_importance_hold_file_lock_assertion(task_t target_task, uint32_t count);
 203 extern int task_importance_drop_file_lock_assertion(task_t target_task, uint32_t count);
 204
 205 extern int task_importance_hold_legacy_external_assertion(task_t target_task, uint32_t count);
 206 extern int task_importance_drop_legacy_external_assertion(task_t target_task, uint32_t count);
 207 #endif /* IMPORTANCE_INHERITANCE */
 208
 209 /* Functions used by process_policy.c */
 210 extern boolean_t proc_task_is_tal(task_t task);
 211
 212 /* Arguments to proc_set_task_ruse_cpu */
 213 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NONE             0x00
 214 #define TASK_POLICY_RESOURCE_ATTRIBUTE_THROTTLE         0x01
 215 #define TASK_POLICY_RESOURCE_ATTRIBUTE_SUSPEND          0x02
 216 #define TASK_POLICY_RESOURCE_ATTRIBUTE_TERMINATE        0x03
 217 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NOTIFY_KQ        0x04
 218 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NOTIFY_EXC       0x05
 219 #define TASK_POLICY_RESOURCE_ATTRIBUTE_DEFAULT          TASK_POLICY_RESOURCE_ATTRIBUTE_NONE
 220
 221 extern int proc_get_task_ruse_cpu(task_t task, uint32_t *policyp, uint8_t *percentagep,
 222                                   uint64_t *intervalp, uint64_t *deadlinep);
 223 extern int proc_set_task_ruse_cpu(task_t task, uint32_t policy, uint8_t percentage,
 224                                   uint64_t interval, uint64_t deadline, int cpumon_entitled);
 225 extern int task_suspend_cpumon(task_t task);
 226 extern int task_resume_cpumon(task_t task);
 227 extern int proc_clear_task_ruse_cpu(task_t task, int cpumon_entitled);
 228
 229 extern int proc_apply_resource_actions(void * p, int type, int action);
 230 extern int proc_restore_resource_actions(void * p, int type, int action);
 231
 232 /* VM/Jetsam importance callouts */
 233 extern int task_low_mem_privileged_listener(task_t task, boolean_t new_value, boolean_t *old_value);
 234 extern boolean_t task_has_been_notified(task_t task, int pressurelevel);
 235 extern boolean_t task_used_for_purging(task_t task, int pressurelevel);
 236 extern void task_mark_has_been_notified(task_t task, int pressurelevel);
 237 extern void task_mark_used_for_purging(task_t task, int pressurelevel);
 238 extern void task_clear_has_been_notified(task_t task, int pressurelevel);
 239 extern void task_clear_used_for_purging(task_t task);
 240 extern int task_importance_estimate(task_t task);
 241
 242 /*
 243  * Allocate/assign a single work interval ID for a thread,
 244  * and support deallocating it.
 245  */
 246 extern kern_return_t thread_policy_create_work_interval(thread_t thread, uint64_t *work_interval_id);
 247 extern kern_return_t thread_policy_destroy_work_interval(thread_t thread, uint64_t work_interval_id);
 248
 249 extern kern_return_t thread_policy_set_internal(thread_t thread, thread_policy_flavor_t flavor,
 250                                                 thread_policy_t policy_info, mach_msg_type_number_t count);
 251
 252 struct promote_token {
 253         uint16_t        pt_basepri;
 254         uint16_t        pt_qos;
 255 };
 256
 257 #define PROMOTE_TOKEN_INIT ((struct promote_token){.pt_basepri = 0, .pt_qos = 0})
 258
 259 extern void thread_user_promotion_add(thread_t thread, thread_t promoter, struct promote_token* promote_token);
 260 extern void thread_user_promotion_update(thread_t thread, thread_t promoter, struct promote_token* promote_token);
 261 extern void thread_user_promotion_drop(thread_t thread);
 262
 263 /* for IPC override management */
 264 extern void thread_add_ipc_override(thread_t thread, uint32_t qos_override);
 265 extern void thread_update_ipc_override(thread_t thread, uint32_t qos_override);
 266 extern void thread_drop_ipc_override(thread_t thread);
 267 extern uint32_t thread_get_ipc_override(thread_t thread);
 268
 269 /*
 270  ******************************
 271  * Mach-internal functionality
 272  ******************************
 273  */
 274
 275 #ifdef MACH_KERNEL_PRIVATE
 276
 277 /*
 278  * this exports the internal policy update calls
 279  * for IPC importance hooks into task policy
 280  */
 281
 282 typedef struct task_pend_token {
 283         uint32_t        tpt_update_sockets      :1,
 284                         tpt_update_timers       :1,
 285                         tpt_update_watchers     :1,
 286                         tpt_update_live_donor   :1,
 287                         tpt_update_coal_sfi     :1,
 288                         tpt_update_throttle     :1,
 289                         tpt_update_thread_sfi   :1,
 290                         tpt_force_recompute_pri :1;
 291 } *task_pend_token_t;
 292
 293 extern void task_policy_update_complete_unlocked(task_t task, task_pend_token_t pend_token);
 294 extern void task_update_boost_locked(task_t task, boolean_t boost_active, task_pend_token_t pend_token);
 295
 296 extern void thread_policy_update_locked(thread_t thread, task_pend_token_t pend_token);
 297 extern void thread_policy_update_complete_unlocked(thread_t task, task_pend_token_t pend_token);
 298
 299 typedef struct {
 300         int             qos_pri[THREAD_QOS_LAST];
 301         int             qos_iotier[THREAD_QOS_LAST];
 302         uint32_t        qos_through_qos[THREAD_QOS_LAST];
 303         uint32_t        qos_latency_qos[THREAD_QOS_LAST];
 304 } qos_policy_params_t;
 305
 306 extern const qos_policy_params_t thread_qos_policy_params;
 307
 308 /* for task policy tracepoints */
 309 /* Convenience functions for munging a policy bitfield into a tracepoint */
 310 uintptr_t threquested_0(thread_t thread);
 311 uintptr_t threquested_1(thread_t thread);
 312 uintptr_t theffective_0(thread_t thread);
 313 uintptr_t theffective_1(thread_t thread);
 314 extern uint32_t  tpending(task_pend_token_t pend_token);
 315
 316 extern void proc_iopol_to_tier(int iopolicy, int *tier, int *passive);
 317 extern int  proc_tier_to_iopol(int tier, int passive);
 318
 319 extern void set_thread_iotier_override(thread_t, int policy);
 320
 321 extern integer_t task_grab_latency_qos(task_t task);
 322 extern void task_policy_create(task_t task, task_t parent_task);
 323 extern void thread_policy_create(thread_t thread);
 324
 325 extern boolean_t task_is_daemon(task_t task);
 326 extern boolean_t task_is_app(task_t task);
 327
 328
 329 #if IMPORTANCE_INHERITANCE
 330 extern boolean_t task_is_marked_importance_donor(task_t task);
 331 extern boolean_t task_is_marked_importance_receiver(task_t task);
 332
 333 extern boolean_t task_is_marked_importance_denap_receiver(task_t task);
 334 #endif /* IMPORTANCE_INHERITANCE */
 335
 336 /* flags for rusage_cpu_flags */
 337 #define TASK_RUSECPU_FLAGS_PROC_LIMIT                   0x01
 338 #define TASK_RUSECPU_FLAGS_PERTHR_LIMIT                 0x02
 339 #define TASK_RUSECPU_FLAGS_DEADLINE                     0x04
 340 #define TASK_RUSECPU_FLAGS_FATAL_CPUMON                 0x08    /* CPU usage monitor violations are fatal */
 341 #define TASK_RUSECPU_FLAGS_FATAL_WAKEUPSMON             0x10    /* wakeups monitor violations are fatal */
 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_ */