osfmk/mach/task_policy.h

   1 /*
   2  * Copyright (c) 2000-2005 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
  29 #ifndef _MACH_TASK_POLICY_H_
  30 #define _MACH_TASK_POLICY_H_
  31
  32 #include <mach/mach_types.h>
  33
  34 /*
  35  * These are the calls for accessing the policy parameters
  36  * of a particular task.
  37  *
  38  * The extra 'get_default' parameter to the second call is
  39  * IN/OUT as follows:
  40  * 1) if asserted on the way in it indicates that the default
  41  * values should be returned, not the ones currently set, in
  42  * this case 'get_default' will always be asserted on return;
  43  * 2) if unasserted on the way in, the current settings are
  44  * desired and if still unasserted on return, then the info
  45  * returned reflects the current settings, otherwise if
  46  * 'get_default' returns asserted, it means that there are no
  47  * current settings due to other parameters taking precedence,
  48  * and the default ones are being returned instead.
  49  */
  50
  51 typedef natural_t       task_policy_flavor_t;
  52 typedef integer_t       *task_policy_t;
  53
  54 /*
  55  *  kern_return_t       task_policy_set(
  56  *                                       task_t                                 task,
  57  *                                       task_policy_flavor_t   flavor,
  58  *                                       task_policy_t                  policy_info,
  59  *                                       mach_msg_type_number_t count);
  60  *
  61  *  kern_return_t       task_policy_get(
  62  *                                       task_t                                 task,
  63  *                                       task_policy_flavor_t   flavor,
  64  *                                       task_policy_t                  policy_info,
  65  *                                       mach_msg_type_number_t *count,
  66  *                                       boolean_t                              *get_default);
  67  */
  68
  69 /*
  70  * Defined flavors.
  71  */
  72 /*
  73  * TASK_CATEGORY_POLICY:
  74  *
  75  * This provides information to the kernel about the role
  76  * of the task in the system.
  77  *
  78  * Parameters:
  79  *
  80  * role: Enumerated as follows:
  81  *
  82  * TASK_UNSPECIFIED is the default, since the role is not
  83  * inherited from the parent.
  84  *
  85  * TASK_FOREGROUND_APPLICATION should be assigned when the
  86  * task is a normal UI application in the foreground from
  87  * the HI point of view.
  88  * **N.B. There may be more than one of these at a given time.
  89  *
  90  * TASK_BACKGROUND_APPLICATION should be assigned when the
  91  * task is a normal UI application in the background from
  92  * the HI point of view.
  93  *
  94  * TASK_CONTROL_APPLICATION should be assigned to the unique
  95  * UI application which implements the pop-up application dialog.
  96  * There can only be one task at a time with this designation,
  97  * which is assigned FCFS.
  98  *
  99  * TASK_GRAPHICS_SERVER should be assigned to the graphics
 100  * management (window) server.  There can only be one task at
 101  * a time with this designation, which is assigned FCFS.
 102  */
 103
 104 #define TASK_CATEGORY_POLICY            1
 105
 106 #define TASK_SUPPRESSION_POLICY         3
 107 #define TASK_POLICY_STATE               4
 108 #define TASK_BASE_QOS_POLICY            8
 109 #define TASK_OVERRIDE_QOS_POLICY        9
 110 #define TASK_BASE_LATENCY_QOS_POLICY    10
 111 #define TASK_BASE_THROUGHPUT_QOS_POLICY 11
 112
 113 typedef enum task_role {
 114         TASK_RENICED                    = -1,
 115         TASK_UNSPECIFIED                = 0,
 116         TASK_FOREGROUND_APPLICATION     = 1,
 117         TASK_BACKGROUND_APPLICATION     = 2,
 118         TASK_CONTROL_APPLICATION        = 3,
 119         TASK_GRAPHICS_SERVER            = 4,
 120         TASK_THROTTLE_APPLICATION       = 5,
 121         TASK_NONUI_APPLICATION          = 6,
 122         TASK_DEFAULT_APPLICATION        = 7,
 123         TASK_DARWINBG_APPLICATION       = 8,
 124 } task_role_t;
 125
 126 struct task_category_policy {
 127         task_role_t             role;
 128 };
 129
 130 typedef struct task_category_policy             task_category_policy_data_t;
 131 typedef struct task_category_policy             *task_category_policy_t;
 132
 133 #define TASK_CATEGORY_POLICY_COUNT      ((mach_msg_type_number_t) \
 134         (sizeof (task_category_policy_data_t) / sizeof (integer_t)))
 135
 136
 137 enum task_latency_qos {
 138         LATENCY_QOS_TIER_UNSPECIFIED = 0x0,
 139         LATENCY_QOS_TIER_0 = ((0xFF << 16) | 1),
 140         LATENCY_QOS_TIER_1 = ((0xFF << 16) | 2),
 141         LATENCY_QOS_TIER_2 = ((0xFF << 16) | 3),
 142         LATENCY_QOS_TIER_3 = ((0xFF << 16) | 4),
 143         LATENCY_QOS_TIER_4 = ((0xFF << 16) | 5),
 144         LATENCY_QOS_TIER_5 = ((0xFF << 16) | 6)
 145 };
 146 typedef integer_t       task_latency_qos_t;
 147 enum task_throughput_qos {
 148         THROUGHPUT_QOS_TIER_UNSPECIFIED = 0x0,
 149         THROUGHPUT_QOS_TIER_0 = ((0xFE << 16) | 1),
 150         THROUGHPUT_QOS_TIER_1 = ((0xFE << 16) | 2),
 151         THROUGHPUT_QOS_TIER_2 = ((0xFE << 16) | 3),
 152         THROUGHPUT_QOS_TIER_3 = ((0xFE << 16) | 4),
 153         THROUGHPUT_QOS_TIER_4 = ((0xFE << 16) | 5),
 154         THROUGHPUT_QOS_TIER_5 = ((0xFE << 16) | 6),
 155 };
 156
 157 #define LATENCY_QOS_LAUNCH_DEFAULT_TIER LATENCY_QOS_TIER_3
 158 #define THROUGHPUT_QOS_LAUNCH_DEFAULT_TIER THROUGHPUT_QOS_TIER_3
 159
 160 typedef integer_t       task_throughput_qos_t;
 161
 162 struct task_qos_policy {
 163         task_latency_qos_t task_latency_qos_tier;
 164         task_throughput_qos_t task_throughput_qos_tier;
 165 };
 166
 167 typedef struct task_qos_policy *task_qos_policy_t;
 168 #define TASK_QOS_POLICY_COUNT   ((mach_msg_type_number_t) \
 169         (sizeof (struct task_qos_policy) / sizeof (integer_t)))
 170
 171 /* These should be removed - they belong in proc_info.h */
 172 #define PROC_FLAG_DARWINBG           0x8000    /* process in darwin background */
 173 #define PROC_FLAG_EXT_DARWINBG           0x10000   /* process in darwin background - external enforcement */
 174 #define PROC_FLAG_IOS_APPLEDAEMON    0x20000   /* process is apple ios daemon */
 175 #define PROC_FLAG_IOS_IMPPROMOTION   0x80000   /* process is apple ios daemon */
 176 #define PROC_FLAG_ADAPTIVE           0x100000  /* Process is adaptive */
 177 #define PROC_FLAG_ADAPTIVE_IMPORTANT 0x200000  /* Process is adaptive, and is currently important */
 178 #define PROC_FLAG_IMPORTANCE_DONOR   0x400000  /* Process is marked as an importance donor */
 179 #define PROC_FLAG_SUPPRESSED         0x800000  /* Process is suppressed */
 180 #define PROC_FLAG_APPLICATION        0x1000000 /* Process is an application */
 181 #define PROC_FLAG_IOS_APPLICATION PROC_FLAG_APPLICATION /* Process is an application */
 182
 183 #ifdef PRIVATE
 184
 185 /*
 186  * Internal bitfields are privately exported for *revlocked*
 187  * tools like msa to decode tracepoints and taskinfo to dump state
 188  *
 189  * These struct definitions *will* change in the future.
 190  * When they do, we will update TASK_POLICY_INTERNAL_STRUCT_VERSION.
 191  */
 192
 193 #define TASK_POLICY_INTERNAL_STRUCT_VERSION 4
 194
 195 #define trp_tal_enabled trp_reserved  /*  trp_tal_enabled is unused, reuse its slot to grow trp_role */
 196
 197 struct task_requested_policy {
 198         uint64_t        trp_int_darwinbg        :1,     /* marked as darwinbg via setpriority */
 199             trp_ext_darwinbg        :1,
 200             trp_int_iotier          :2,                 /* IO throttle tier */
 201             trp_ext_iotier          :2,
 202             trp_int_iopassive       :1,                 /* should IOs cause lower tiers to be throttled */
 203             trp_ext_iopassive       :1,
 204             trp_bg_iotier           :2,                 /* what IO throttle tier should apply to me when I'm darwinbg? (pushed to threads) */
 205             trp_terminated          :1,                 /* all throttles should be removed for quick exit or SIGTERM handling */
 206             trp_base_latency_qos    :3,                 /* Timer latency QoS */
 207             trp_base_through_qos    :3,                 /* Computation throughput QoS */
 208
 209             trp_apptype             :3,                 /* What apptype did launchd tell us this was (inherited) */
 210             trp_boosted             :1,                 /* Has a non-zero importance assertion count */
 211             trp_role                :5,                 /* task's system role */
 212             trp_over_latency_qos    :3,                 /* Timer latency QoS override */
 213             trp_over_through_qos    :3,                 /* Computation throughput QoS override */
 214             trp_sfi_managed         :1,                 /* SFI Managed task */
 215             trp_qos_clamp           :3,                 /* task qos clamp */
 216
 217         /* suppression policies (non-embedded only) */
 218             trp_sup_active          :1,                 /* Suppression is on */
 219             trp_sup_lowpri_cpu      :1,                 /* Wants low priority CPU (MAXPRI_THROTTLE) */
 220             trp_sup_timer           :3,                 /* Wanted timer throttling QoS tier */
 221             trp_sup_disk            :1,                 /* Wants disk throttling */
 222             trp_sup_throughput      :3,                 /* Wants throughput QoS tier */
 223             trp_sup_cpu             :1,                 /* Wants suppressed CPU priority (MAXPRI_SUPPRESSED) */
 224             trp_sup_bg_sockets      :1,                 /* Wants background sockets */
 225
 226             trp_reserved            :17;
 227 };
 228
 229 struct task_effective_policy {
 230         uint64_t        tep_darwinbg            :1,     /* marked as 'background', and sockets are marked bg when created */
 231             tep_lowpri_cpu          :1,                 /* cpu priority == MAXPRI_THROTTLE */
 232             tep_io_tier             :2,                 /* effective throttle tier */
 233             tep_io_passive          :1,                 /* should IOs cause lower tiers to be throttled */
 234             tep_all_sockets_bg      :1,                 /* All existing sockets in process are marked as bg (thread: all created by thread) */
 235             tep_new_sockets_bg      :1,                 /* Newly created sockets should be marked as bg */
 236             tep_bg_iotier           :2,                 /* What throttle tier should I be in when darwinbg is set? */
 237             tep_terminated          :1,                 /* all throttles have been removed for quick exit or SIGTERM handling */
 238             tep_qos_ui_is_urgent    :1,                 /* bump UI-Interactive QoS up to the urgent preemption band */
 239             tep_latency_qos         :3,                 /* Timer latency QoS level */
 240             tep_through_qos         :3,                 /* Computation throughput QoS level */
 241
 242             tep_tal_engaged         :1,                 /* TAL mode is in effect */
 243             tep_watchers_bg         :1,                 /* watchers are BG-ed */
 244             tep_sup_active          :1,                 /* suppression behaviors are in effect */
 245             tep_role                :4,                 /* task's system role */
 246             tep_suppressed_cpu      :1,                 /* cpu priority == MAXPRI_SUPPRESSED (trumped by lowpri_cpu) */
 247             tep_sfi_managed         :1,                 /* SFI Managed task */
 248             tep_live_donor          :1,                 /* task is a live importance boost donor */
 249             tep_qos_clamp           :3,                 /* task qos clamp (applies to qos-disabled threads too) */
 250             tep_qos_ceiling         :3,                 /* task qos ceiling (applies to only qos-participating threads) */
 251             tep_adaptive_bg         :1,                 /* task is bg solely due to the adaptive daemon clamp */
 252
 253             tep_reserved            :30;
 254 };
 255
 256 #endif /* PRIVATE */
 257
 258 #ifdef MACH_KERNEL_PRIVATE
 259
 260 extern const struct task_requested_policy default_task_requested_policy;
 261 extern const struct task_effective_policy default_task_effective_policy;
 262
 263 extern kern_return_t
 264     qos_latency_policy_validate(task_latency_qos_t);
 265
 266 extern kern_return_t
 267     qos_throughput_policy_validate(task_throughput_qos_t);
 268
 269 extern uint32_t
 270     qos_extract(uint32_t);
 271
 272 extern uint32_t
 273     qos_latency_policy_package(uint32_t);
 274 extern uint32_t
 275     qos_throughput_policy_package(uint32_t);
 276
 277 #endif /* MACH_KERNEL_PRIVATE */
 278
 279 #ifdef PRIVATE
 280
 281 /*
 282  * Control structure for applying suppression behaviors to tasks
 283  */
 284 struct task_suppression_policy {
 285         integer_t active;
 286         integer_t lowpri_cpu;  /* priority MAXPRI_THROTTLE cpu */
 287         integer_t timer_throttle;
 288         integer_t disk_throttle;
 289         integer_t cpu_limit;
 290         integer_t suspend;
 291         integer_t throughput_qos;
 292         integer_t suppressed_cpu; /* priority MAXPRI_SUPPRESSED cpu */
 293         integer_t background_sockets;
 294         integer_t reserved[7];
 295 };
 296
 297 typedef struct task_suppression_policy *task_suppression_policy_t;
 298
 299 #define TASK_SUPPRESSION_POLICY_COUNT   ((mach_msg_type_number_t) \
 300         (sizeof (struct task_suppression_policy) / sizeof (integer_t)))
 301
 302 struct task_policy_state {
 303         uint64_t requested;
 304         uint64_t effective;
 305         uint64_t pending;
 306         uint32_t imp_assertcnt;
 307         uint32_t imp_externcnt;
 308         uint64_t flags;
 309         uint64_t imp_transitions;
 310         uint64_t tps_requested_policy;
 311         uint64_t tps_effective_policy;
 312 };
 313
 314 typedef struct task_policy_state *task_policy_state_t;
 315
 316 #define TASK_POLICY_STATE_COUNT ((mach_msg_type_number_t) \
 317         (sizeof (struct task_policy_state) / sizeof (integer_t)))
 318
 319
 320 /*
 321  * Definitions for munging and unmunging a policy struct
 322  * Used in task_policy_state and in tracepoints
 323  *
 324  * Note: this is tightly bound to the implementation of task policy
 325  * and the values exported through this API may change or change meaning at any time
 326  *
 327  * Do not rely on these values, especially apptype, to decide behaviors at runtime.
 328  *
 329  * All per-thread state must be in the first 32 bits of the bitfield.
 330  */
 331
 332 #define TASK_APPTYPE_NONE                0
 333 #define TASK_APPTYPE_DAEMON_INTERACTIVE  1
 334 #define TASK_APPTYPE_DAEMON_STANDARD     2
 335 #define TASK_APPTYPE_DAEMON_ADAPTIVE     3
 336 #define TASK_APPTYPE_DAEMON_BACKGROUND   4
 337 #define TASK_APPTYPE_APP_DEFAULT         5
 338 #define TASK_APPTYPE_APP_TAL             6 /* unused */
 339 #define TASK_APPTYPE_DRIVER              7
 340
 341 /* task policy state flags */
 342 #define TASK_IMP_RECEIVER                    0x00000001
 343 #define TASK_IMP_DONOR                       0x00000002
 344 #define TASK_IMP_LIVE_DONOR                  0x00000004
 345 #define TASK_DENAP_RECEIVER                  0x00000008
 346 #define TASK_IS_PIDSUSPENDED                 0x00000010
 347
 348 /* requested_policy */
 349 #define POLICY_REQ_INT_DARWIN_BG             0x00000001
 350 #define POLICY_REQ_EXT_DARWIN_BG             0x00000002
 351 #define POLICY_REQ_INT_IO_TIER_MASK          0x0000000c /* 2 bits */
 352 #define POLICY_REQ_INT_IO_TIER_SHIFT         2
 353 #define POLICY_REQ_EXT_IO_TIER_MASK          0x00000030 /* 2 bits */
 354 #define POLICY_REQ_EXT_IO_TIER_SHIFT         4
 355 #define POLICY_REQ_INT_PASSIVE_IO            0x00000040
 356 #define POLICY_REQ_EXT_PASSIVE_IO            0x00000080
 357 #define POLICY_REQ_BG_IOTIER_MASK            0x00000300 /* 2 bits */
 358 #define POLICY_REQ_BG_IOTIER_SHIFT           8
 359
 360 /* thread requested policy */
 361 #define POLICY_REQ_PIDBIND_BG                0x00000400
 362 #define POLICY_REQ_WORKQ_BG                  0x00000800 /* deprecated */
 363 #define POLICY_REQ_TH_QOS_MASK               0x07000000 /* 3 bits (overlaps with ROLE) */
 364 #define POLICY_REQ_TH_QOS_SHIFT              24
 365 #define POLICY_REQ_TH_QOS_OVER_MASK          0x70000000 /* 3 bits (overlaps with TAL and SFI) */
 366 #define POLICY_REQ_TH_QOS_OVER_SHIFT         28
 367
 368 /* task_requested_policy */
 369 #define POLICY_REQ_TERMINATED                0x00001000
 370 #define POLICY_REQ_BOOSTED                   0x00002000
 371 #define POLICY_REQ_INT_GPU_DENY              0x00004000
 372 #define POLICY_REQ_EXT_GPU_DENY              0x00008000
 373 #define POLICY_REQ_APPTYPE_MASK              0x00070000 /* 3 bits */
 374 #define POLICY_REQ_APPTYPE_SHIFT             16
 375 #define POLICY_REQ_BASE_LATENCY_QOS_MASK     0x00700000 /* 3 bits */
 376 #define POLICY_REQ_BASE_LATENCY_QOS_SHIFT    20
 377 #define POLICY_REQ_ROLE_MASK                 0x07000000 /* 3 bits */
 378 #define POLICY_REQ_ROLE_SHIFT                24
 379 #define POLICY_REQ_TAL_ENABLED               0x40000000
 380 #define POLICY_REQ_SFI_MANAGED               0x80000000
 381
 382 /* requested suppression behaviors (note: clipped off in 32-bit tracepoints) */
 383 #define POLICY_REQ_SUP_ACTIVE                0x0000000100000000
 384 #define POLICY_REQ_SUP_LOWPRI_CPU            0x0000000200000000
 385 #define POLICY_REQ_SUP_CPU                   0x0000000400000000
 386 #define POLICY_REQ_SUP_DISK_THROTTLE         0x0000003000000000 /* 2 bits */
 387 #define POLICY_REQ_SUP_CPU_LIMIT             0x0000004000000000
 388 #define POLICY_REQ_SUP_SUSPEND               0x0000008000000000
 389 #define POLICY_REQ_OVER_LATENCY_QOS_MASK     0x0000070000000000 /* 3 bits */
 390 #define POLICY_REQ_OVER_LATENCY_QOS_SHIFT    40
 391 #define POLICY_REQ_BASE_THROUGH_QOS_MASK     0x0000700000000000 /* 3 bits */
 392 #define POLICY_REQ_BASE_THROUGH_QOS_SHIFT    44
 393 #define POLICY_REQ_OVER_THROUGH_QOS_MASK     0x0007000000000000 /* 3 bits */
 394 #define POLICY_REQ_OVER_THROUGH_QOS_SHIFT    48
 395 #define POLICY_REQ_SUP_TIMER_THROTTLE_MASK   0x0070000000000000 /* 3 bits */
 396 #define POLICY_REQ_SUP_TIMER_THROTTLE_SHIFT  52
 397 #define POLICY_REQ_SUP_THROUGHPUT_MASK       0x0700000000000000 /* 3 bits */
 398 #define POLICY_REQ_SUP_THROUGHPUT_SHIFT      56
 399 #define POLICY_REQ_SUP_BG_SOCKETS            0x0800008000000000
 400 #define POLICY_REQ_QOS_CLAMP_MASK            0x7000000000000000 /* 3 bits */
 401 #define POLICY_REQ_QOS_CLAMP_SHIFT           60
 402
 403 /* effective policy */
 404 #define POLICY_EFF_IO_TIER_MASK              0x00000003 /* 2 bits */
 405 #define POLICY_EFF_IO_TIER_SHIFT             0
 406 #define POLICY_EFF_IO_PASSIVE                0x00000008
 407 #define POLICY_EFF_DARWIN_BG                 0x00000010
 408 #define POLICY_EFF_LOWPRI_CPU                0x00000020
 409 #define POLICY_EFF_ALL_SOCKETS_BG            0x00000040
 410 #define POLICY_EFF_NEW_SOCKETS_BG            0x00000080
 411 #define POLICY_EFF_BG_IOTIER_MASK            0x00000300 /* 2 bits */
 412 #define POLICY_EFF_BG_IOTIER_SHIFT           8
 413 #define POLICY_EFF_TERMINATED                0x00000400
 414 #define POLICY_EFF_QOS_UI_IS_URGENT          0x80000000
 415
 416 /* thread effective policy */
 417 #define POLICY_EFF_TH_QOS_MASK               0x00700000 /* 3 bits (overlaps with ROLE) */
 418 #define POLICY_EFF_TH_QOS_SHIFT              20
 419 #define POLICY_EFF_LATENCY_QOS_MASK          0x00070000 /* 3 bits */
 420 #define POLICY_EFF_LATENCY_QOS_SHIFT         16
 421 #define POLICY_EFF_THROUGH_QOS_MASK          0x07000000 /* 3 bits */
 422 #define POLICY_EFF_THROUGH_QOS_SHIFT         24
 423
 424 /* task effective policy */
 425 #define POLICY_EFF_GPU_DENY                  0x00001000
 426 #define POLICY_EFF_TAL_ENGAGED               0x00002000
 427 #define POLICY_EFF_SUSPENDED                 0x00004000
 428 #define POLICY_EFF_WATCHERS_BG               0x00008000
 429 #define POLICY_EFF_SUP_ACTIVE                0x00080000
 430 #define POLICY_EFF_ROLE_MASK                 0x00700000 /* 3 bits */
 431 #define POLICY_EFF_ROLE_SHIFT                20
 432 #define POLICY_EFF_SUP_CPU                   0x00800000
 433 #define POLICY_EFF_SFI_MANAGED               0x08000000
 434 #define POLICY_EFF_QOS_CEILING_MASK          0x70000000
 435 #define POLICY_EFF_QOS_CEILING_SHIFT         28
 436
 437 /* pending policy */
 438 #define POLICY_PEND_UPDATING                 0x00000001
 439 #define POLICY_PEND_SOCKETS                  0x00000002
 440 #define POLICY_PEND_TIMERS                   0x00000004
 441 #define POLICY_PEND_WATCHERS                 0x00000008
 442
 443 #endif /* PRIVATE */
 444
 445 #endif  /* _MACH_TASK_POLICY_H_ */