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 #define TASK_POLICY_QOS_SYNC_IPC_OVERRIDE    0x3E
 112
 113 #define TASK_POLICY_MAX                 0x3F
 114
 115 /* The main entrance to task policy is this function */
 116 extern void proc_set_task_policy(task_t task, int category, int flavor, int value);
 117 extern int  proc_get_task_policy(task_t task, int category, int flavor);
 118
 119 extern void proc_set_thread_policy(thread_t thread, int category, int flavor, int value);
 120 extern int  proc_get_thread_policy(thread_t thread, int category, int flavor);
 121
 122 /* For use when you don't already hold a reference on the target thread */
 123 extern void proc_set_thread_policy_with_tid(task_t task, uint64_t tid, int category, int flavor, int value);
 124
 125
 126 /* Functions used by kern_resource.c */
 127 extern boolean_t thread_has_qos_policy(thread_t thread);
 128 extern kern_return_t thread_remove_qos_policy(thread_t thread);
 129
 130 extern int  proc_darwin_role_to_task_role(int darwin_role, int* task_role);
 131 extern int  proc_task_role_to_darwin_role(int task_role);
 132
 133 /* Functions used by kern_exec.c */
 134 extern void task_set_main_thread_qos(task_t task, thread_t main_thread);
 135 extern void proc_set_task_spawnpolicy(task_t task, int apptype, int qos_clamp, int role,
 136                                       ipc_port_t * portwatch_ports, int portwatch_count);
 137 extern void proc_inherit_task_role(task_t new_task, task_t old_task);
 138
 139 /* IO Throttle tiers */
 140 #define THROTTLE_LEVEL_NONE     -1
 141 #define THROTTLE_LEVEL_TIER0     0      /* IOPOL_NORMAL, IOPOL_DEFAULT, IOPOL_PASSIVE */
 142
 143 #define THROTTLE_LEVEL_THROTTLED 1
 144 #define THROTTLE_LEVEL_TIER1     1      /* IOPOL_STANDARD */
 145 #define THROTTLE_LEVEL_TIER2     2      /* IOPOL_UTILITY */
 146 #define THROTTLE_LEVEL_TIER3     3      /* IOPOL_THROTTLE */
 147
 148 #define THROTTLE_LEVEL_START     0
 149 #define THROTTLE_LEVEL_END       3
 150
 151 #define THROTTLE_LEVEL_COMPRESSOR_TIER0         THROTTLE_LEVEL_TIER0
 152 #define THROTTLE_LEVEL_COMPRESSOR_TIER1         THROTTLE_LEVEL_TIER1
 153 #define THROTTLE_LEVEL_COMPRESSOR_TIER2         THROTTLE_LEVEL_TIER2
 154
 155 #if CONFIG_EMBEDDED
 156 #define THROTTLE_LEVEL_PAGEOUT_THROTTLED        THROTTLE_LEVEL_TIER3
 157 #define THROTTLE_LEVEL_PAGEOUT_UNTHROTTLED      THROTTLE_LEVEL_TIER1
 158 #else
 159 #define THROTTLE_LEVEL_PAGEOUT_THROTTLED        THROTTLE_LEVEL_TIER2
 160 #define THROTTLE_LEVEL_PAGEOUT_UNTHROTTLED      THROTTLE_LEVEL_TIER1
 161 #endif
 162
 163 #if CONFIG_IOSCHED
 164 #define IOSCHED_METADATA_TIER                   THROTTLE_LEVEL_TIER1
 165 #endif /* CONFIG_IOSCHED */
 166
 167 extern int proc_get_darwinbgstate(task_t task, uint32_t *flagsp);
 168 extern int task_get_apptype(task_t);
 169
 170 #ifdef MACH_BSD
 171 extern void proc_apply_task_networkbg(void * bsd_info, thread_t thread);
 172 #endif /* MACH_BSD */
 173
 174 /* Functions used by pthread_shims.c */
 175 extern boolean_t proc_thread_qos_add_override(task_t task, thread_t thread, uint64_t tid,
 176                                               int override_qos, boolean_t first_override_for_resource,
 177                                               user_addr_t resource, int resource_type);
 178 extern int proc_thread_qos_add_override_check_owner(thread_t thread, int override_qos,
 179                 boolean_t first_override_for_resource, user_addr_t resource, int resource_type,
 180                 user_addr_t user_lock_addr, mach_port_name_t user_lock_owner);
 181 extern boolean_t proc_thread_qos_remove_override(task_t task, thread_t thread, uint64_t tid,
 182                                                  user_addr_t resource, int resource_type);
 183 extern boolean_t proc_thread_qos_reset_override(task_t task, thread_t thread, uint64_t tid,
 184                                                  user_addr_t resource, int resource_type);
 185 extern int proc_thread_qos_squash_override(thread_t thread, user_addr_t resource, int resource_type);
 186
 187 extern kern_return_t
 188 thread_set_workq_qos(thread_t thread, int qos_tier, int relprio);
 189 extern kern_return_t
 190 thread_set_workq_pri(thread_t thread, integer_t priority, integer_t policy);
 191
 192 extern int
 193 task_get_default_manager_qos(task_t task);
 194
 195 extern void proc_thread_qos_deallocate(thread_t thread);
 196
 197 extern int task_clear_cpuusage(task_t task, int cpumon_entitled);
 198
 199 #if CONFIG_EMBEDDED
 200 /* Taskwatch related external BSD interface */
 201 extern int proc_lf_pidbind(task_t curtask, uint64_t tid, task_t target_task, int bind);
 202 #endif /* CONFIG_EMBEDDED */
 203
 204 /* Importance inheritance functions not under IMPORTANCE_INHERITANCE */
 205 extern void task_importance_mark_donor(task_t task, boolean_t donating);
 206 extern void task_importance_reset(task_t task);
 207
 208 #if IMPORTANCE_INHERITANCE
 209 extern boolean_t task_is_importance_donor(task_t task);
 210 extern boolean_t task_is_importance_receiver_type(task_t task);
 211
 212 extern int task_importance_hold_file_lock_assertion(task_t target_task, uint32_t count);
 213 extern int task_importance_drop_file_lock_assertion(task_t target_task, uint32_t count);
 214
 215 extern int task_importance_hold_legacy_external_assertion(task_t target_task, uint32_t count);
 216 extern int task_importance_drop_legacy_external_assertion(task_t target_task, uint32_t count);
 217 #endif /* IMPORTANCE_INHERITANCE */
 218
 219 /* Functions used by process_policy.c */
 220 extern boolean_t proc_task_is_tal(task_t task);
 221
 222 /* Arguments to proc_set_task_ruse_cpu */
 223 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NONE             0x00
 224 #define TASK_POLICY_RESOURCE_ATTRIBUTE_THROTTLE         0x01
 225 #define TASK_POLICY_RESOURCE_ATTRIBUTE_SUSPEND          0x02
 226 #define TASK_POLICY_RESOURCE_ATTRIBUTE_TERMINATE        0x03
 227 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NOTIFY_KQ        0x04
 228 #define TASK_POLICY_RESOURCE_ATTRIBUTE_NOTIFY_EXC       0x05
 229 #define TASK_POLICY_RESOURCE_ATTRIBUTE_DEFAULT          TASK_POLICY_RESOURCE_ATTRIBUTE_NONE
 230
 231 extern int proc_get_task_ruse_cpu(task_t task, uint32_t *policyp, uint8_t *percentagep,
 232                                   uint64_t *intervalp, uint64_t *deadlinep);
 233 extern int proc_set_task_ruse_cpu(task_t task, uint32_t policy, uint8_t percentage,
 234                                   uint64_t interval, uint64_t deadline, int cpumon_entitled);
 235 extern int task_suspend_cpumon(task_t task);
 236 extern int task_resume_cpumon(task_t task);
 237 extern int proc_clear_task_ruse_cpu(task_t task, int cpumon_entitled);
 238
 239 extern int proc_apply_resource_actions(void * p, int type, int action);
 240 extern int proc_restore_resource_actions(void * p, int type, int action);
 241
 242 /* VM/Jetsam importance callouts */
 243 extern int task_low_mem_privileged_listener(task_t task, boolean_t new_value, boolean_t *old_value);
 244 extern boolean_t task_has_been_notified(task_t task, int pressurelevel);
 245 extern boolean_t task_used_for_purging(task_t task, int pressurelevel);
 246 extern void task_mark_has_been_notified(task_t task, int pressurelevel);
 247 extern void task_mark_used_for_purging(task_t task, int pressurelevel);
 248 extern void task_clear_has_been_notified(task_t task, int pressurelevel);
 249 extern void task_clear_used_for_purging(task_t task);
 250 extern int task_importance_estimate(task_t task);
 251
 252 extern kern_return_t thread_policy_set_internal(thread_t thread, thread_policy_flavor_t flavor,
 253                                                 thread_policy_t policy_info, mach_msg_type_number_t count);
 254
 255 struct promote_token {
 256         uint16_t        pt_basepri;
 257         uint16_t        pt_qos;
 258 };
 259
 260 #define PROMOTE_TOKEN_INIT ((struct promote_token){.pt_basepri = 0, .pt_qos = 0})
 261
 262 extern void thread_user_promotion_add(thread_t thread, thread_t promoter, struct promote_token* promote_token);
 263 extern void thread_user_promotion_update(thread_t thread, thread_t promoter, struct promote_token* promote_token);
 264 extern void thread_user_promotion_drop(thread_t thread);
 265
 266 /* for thread exec promotion */
 267 #define EXEC_BOOST_PRIORITY 31
 268
 269 extern void thread_set_exec_promotion(thread_t thread);
 270 extern void thread_clear_exec_promotion(thread_t thread);
 271
 272 /* for IPC override management */
 273 extern void thread_add_ipc_override(thread_t thread, uint32_t qos_override);
 274 extern void thread_update_ipc_override(thread_t thread, uint32_t qos_override);
 275 extern void thread_drop_ipc_override(thread_t thread);
 276 extern void thread_add_sync_ipc_override(thread_t thread);
 277 extern void thread_drop_sync_ipc_override(thread_t thread);
 278 extern uint32_t thread_get_ipc_override(thread_t thread);
 279
 280 /*
 281  ******************************
 282  * Mach-internal functionality
 283  ******************************
 284  */
 285
 286 #ifdef MACH_KERNEL_PRIVATE
 287
 288 /*
 289  * this exports the internal policy update calls
 290  * for IPC importance hooks into task policy
 291  */
 292
 293 typedef struct task_pend_token {
 294         uint32_t        tpt_update_sockets      :1,
 295                         tpt_update_timers       :1,
 296                         tpt_update_watchers     :1,
 297                         tpt_update_live_donor   :1,
 298                         tpt_update_coal_sfi     :1,
 299                         tpt_update_throttle     :1,
 300                         tpt_update_thread_sfi   :1,
 301                         tpt_force_recompute_pri :1,
 302                         tpt_update_tg_ui_flag   :1;
 303 } *task_pend_token_t;
 304
 305 extern void task_policy_update_complete_unlocked(task_t task, task_pend_token_t pend_token);
 306 extern void task_update_boost_locked(task_t task, boolean_t boost_active, task_pend_token_t pend_token);
 307
 308 extern void thread_policy_update_locked(thread_t thread, task_pend_token_t pend_token);
 309 extern void thread_policy_update_complete_unlocked(thread_t task, task_pend_token_t pend_token);
 310
 311 typedef struct {
 312         int             qos_pri[THREAD_QOS_LAST];
 313         int             qos_iotier[THREAD_QOS_LAST];
 314         uint32_t        qos_through_qos[THREAD_QOS_LAST];
 315         uint32_t        qos_latency_qos[THREAD_QOS_LAST];
 316 } qos_policy_params_t;
 317
 318 extern const qos_policy_params_t thread_qos_policy_params;
 319
 320 /* for task policy tracepoints */
 321 /* Convenience functions for munging a policy bitfield into a tracepoint */
 322 uintptr_t threquested_0(thread_t thread);
 323 uintptr_t threquested_1(thread_t thread);
 324 uintptr_t theffective_0(thread_t thread);
 325 uintptr_t theffective_1(thread_t thread);
 326 extern uint32_t  tpending(task_pend_token_t pend_token);
 327
 328 extern void proc_iopol_to_tier(int iopolicy, int *tier, int *passive);
 329 extern int  proc_tier_to_iopol(int tier, int passive);
 330
 331 extern void set_thread_iotier_override(thread_t, int policy);
 332
 333 extern integer_t task_grab_latency_qos(task_t task);
 334 extern void task_policy_create(task_t task, task_t parent_task);
 335 extern void thread_policy_create(thread_t thread);
 336
 337 extern boolean_t task_is_daemon(task_t task);
 338 extern boolean_t task_is_app(task_t task);
 339
 340 #if CONFIG_EMBEDDED
 341 /* Taskwatch related external interface */
 342 extern void thead_remove_taskwatch(thread_t thread);
 343 extern void task_removewatchers(task_t task);
 344 extern void task_watch_init(void);
 345
 346 typedef struct task_watcher task_watch_t;
 347 #endif /* CONFIG_EMBEDDED */
 348
 349 #if IMPORTANCE_INHERITANCE
 350 extern boolean_t task_is_marked_importance_donor(task_t task);
 351 extern boolean_t task_is_marked_importance_receiver(task_t task);
 352
 353 extern boolean_t task_is_marked_importance_denap_receiver(task_t task);
 354 #endif /* IMPORTANCE_INHERITANCE */
 355
 356 /* flags for rusage_cpu_flags */
 357 #define TASK_RUSECPU_FLAGS_PROC_LIMIT                   0x01
 358 #define TASK_RUSECPU_FLAGS_PERTHR_LIMIT                 0x02
 359 #define TASK_RUSECPU_FLAGS_DEADLINE                     0x04
 360 #define TASK_RUSECPU_FLAGS_FATAL_CPUMON                 0x08    /* CPU usage monitor violations are fatal */
 361 #define TASK_RUSECPU_FLAGS_FATAL_WAKEUPSMON             0x10    /* wakeups monitor violations are fatal */
 362
 363 extern void proc_init_cpumon_params(void);
 364 extern void thread_policy_init(void);
 365
 366 int task_compute_main_thread_qos(task_t task);
 367
 368 /* thread policy internals */
 369 extern void thread_policy_reset(thread_t thread);
 370 extern kern_return_t thread_set_mode_and_absolute_pri(thread_t thread, integer_t policy, integer_t priority);
 371
 372 extern void thread_policy_update_tasklocked(thread_t thread, integer_t priority, integer_t max_priority, task_pend_token_t pend_token);
 373
 374 #include "mach/resource_notify.h"       /* from MIG */
 375
 376 /*! @function   send_resource_violation
 377     @abstract   send usage monitor violation notification
 378
 379     @param  violator  the task (process) violating its CPU budget
 380     @param  ledger_info   the entry tracking the resource limit
 381     @param  flags   see constants for type in sys/reason.h
 382
 383     @result KERN_SUCCESS if the message was sent
 384
 385     @discussion
 386         send_resource_violation() calls the corresponding MIG routine
 387         over the host special RESOURCE_NOTIFY port.
 388 */
 389 kern_return_t send_resource_violation(typeof(send_cpu_usage_violation),
 390                                       task_t violator,
 391                                       struct ledger_entry_info *ledger_info,
 392                                       resource_notify_flags_t flags);
 393
 394 /*! @function   trace_resource_violation
 395     @abstract   trace violations on K32/64
 396
 397     @param  code   the (K64) DBG_MACH_RESOURCE trace code
 398     @param  ledger_info   the entry tracking the resource limit
 399
 400     @discussion
 401         Trace observed usage and corresponding limit on K32 or K64.  On
 402         K32, a pair of trace points are used.  The low nibble of the K32
 403         trace points must start at double the low nibble of the provided
 404         K64 trace point.  For example:
 405                 #define LOGWRITES_VIOLATED              0x022
 406                 ...
 407                 #define LOGWRITES_VIOLATED_K32A         0x024
 408                 #define LOGWRITES_VIOLATED_K32B         0x025
 409 */
 410 void trace_resource_violation(uint16_t code,
 411                               struct ledger_entry_info *ledger_info);
 412
 413 #endif /* MACH_KERNEL_PRIVATE */
 414
 415 #endif /* XNU_KERNEL_PRIVATE */
 416
 417 #endif /* _KERN_POLICY_INTERNAL_H_ */