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
 114 enum task_role {
 115         TASK_RENICED                    = -1,
 116         TASK_UNSPECIFIED                = 0,
 117         TASK_FOREGROUND_APPLICATION     = 1,
 118         TASK_BACKGROUND_APPLICATION     = 2,
 119         TASK_CONTROL_APPLICATION        = 3,
 120         TASK_GRAPHICS_SERVER            = 4,
 121         TASK_THROTTLE_APPLICATION       = 5,
 122         TASK_NONUI_APPLICATION          = 6,
 123         TASK_DEFAULT_APPLICATION        = 7,
 124         TASK_DARWINBG_APPLICATION       = 8,
 125 };
 126
 127 typedef integer_t       task_role_t;
 128
 129 struct task_category_policy {
 130         task_role_t             role;
 131 };
 132
 133 typedef struct task_category_policy             task_category_policy_data_t;
 134 typedef struct task_category_policy             *task_category_policy_t;
 135
 136 #define TASK_CATEGORY_POLICY_COUNT      ((mach_msg_type_number_t) \
 137         (sizeof (task_category_policy_data_t) / sizeof (integer_t)))
 138
 139
 140 enum task_latency_qos {
 141         LATENCY_QOS_TIER_UNSPECIFIED = 0x0,
 142         LATENCY_QOS_TIER_0 = ((0xFF << 16) | 1),
 143         LATENCY_QOS_TIER_1 = ((0xFF << 16) | 2),
 144         LATENCY_QOS_TIER_2 = ((0xFF << 16) | 3),
 145         LATENCY_QOS_TIER_3 = ((0xFF << 16) | 4),
 146         LATENCY_QOS_TIER_4 = ((0xFF << 16) | 5),
 147         LATENCY_QOS_TIER_5 = ((0xFF << 16) | 6)
 148 };
 149 typedef integer_t       task_latency_qos_t;
 150 enum task_throughput_qos {
 151         THROUGHPUT_QOS_TIER_UNSPECIFIED = 0x0,
 152         THROUGHPUT_QOS_TIER_0 = ((0xFE << 16) | 1),
 153         THROUGHPUT_QOS_TIER_1 = ((0xFE << 16) | 2),
 154         THROUGHPUT_QOS_TIER_2 = ((0xFE << 16) | 3),
 155         THROUGHPUT_QOS_TIER_3 = ((0xFE << 16) | 4),
 156         THROUGHPUT_QOS_TIER_4 = ((0xFE << 16) | 5),
 157         THROUGHPUT_QOS_TIER_5 = ((0xFE << 16) | 6),
 158 };
 159
 160 #define LATENCY_QOS_LAUNCH_DEFAULT_TIER LATENCY_QOS_TIER_3
 161 #define THROUGHPUT_QOS_LAUNCH_DEFAULT_TIER THROUGHPUT_QOS_TIER_3
 162
 163 typedef integer_t       task_throughput_qos_t;
 164
 165 struct task_qos_policy {
 166         task_latency_qos_t task_latency_qos_tier;
 167         task_throughput_qos_t task_throughput_qos_tier;
 168 };
 169
 170 typedef struct task_qos_policy *task_qos_policy_t;
 171 #define TASK_QOS_POLICY_COUNT   ((mach_msg_type_number_t) \
 172         (sizeof (struct task_qos_policy) / sizeof (integer_t)))
 173
 174 /* These should be removed - they belong in proc_info.h */
 175 #define PROC_FLAG_DARWINBG           0x8000    /* process in darwin background */
 176 #define PROC_FLAG_EXT_DARWINBG           0x10000   /* process in darwin background - external enforcement */
 177 #define PROC_FLAG_IOS_APPLEDAEMON    0x20000   /* process is apple ios daemon */
 178 #define PROC_FLAG_IOS_IMPPROMOTION   0x80000   /* process is apple ios daemon */
 179 #define PROC_FLAG_ADAPTIVE           0x100000  /* Process is adaptive */
 180 #define PROC_FLAG_ADAPTIVE_IMPORTANT 0x200000  /* Process is adaptive, and is currently important */
 181 #define PROC_FLAG_IMPORTANCE_DONOR   0x400000  /* Process is marked as an importance donor */
 182 #define PROC_FLAG_SUPPRESSED         0x800000  /* Process is suppressed */
 183 #define PROC_FLAG_APPLICATION        0x1000000 /* Process is an application */
 184 #define PROC_FLAG_IOS_APPLICATION PROC_FLAG_APPLICATION /* Process is an application */
 185
 186 #ifdef PRIVATE
 187
 188 /*
 189  * Internal bitfields are privately exported for *revlocked*
 190  * tools like msa to decode tracepoints and taskinfo to dump state
 191  *
 192  * These struct definitions *will* change in the future.
 193  * When they do, we will update TASK_POLICY_INTERNAL_STRUCT_VERSION.
 194  */
 195
 196 #define TASK_POLICY_INTERNAL_STRUCT_VERSION 2
 197
 198 struct task_requested_policy {
 199         uint64_t        trp_int_darwinbg        :1,     /* marked as darwinbg via setpriority */
 200             trp_ext_darwinbg        :1,
 201             trp_int_iotier          :2,                 /* IO throttle tier */
 202             trp_ext_iotier          :2,
 203             trp_int_iopassive       :1,                 /* should IOs cause lower tiers to be throttled */
 204             trp_ext_iopassive       :1,
 205             trp_bg_iotier           :2,                 /* what IO throttle tier should apply to me when I'm darwinbg? (pushed to threads) */
 206             trp_terminated          :1,                 /* all throttles should be removed for quick exit or SIGTERM handling */
 207             trp_base_latency_qos    :3,                 /* Timer latency QoS */
 208             trp_base_through_qos    :3,                 /* Computation throughput QoS */
 209
 210             trp_apptype             :3,                 /* What apptype did launchd tell us this was (inherited) */
 211             trp_boosted             :1,                 /* Has a non-zero importance assertion count */
 212             trp_role                :4,                 /* task's system role */
 213             trp_tal_enabled         :1,                 /* TAL mode is enabled */
 214             trp_over_latency_qos    :3,                 /* Timer latency QoS override */
 215             trp_over_through_qos    :3,                 /* Computation throughput QoS override */
 216             trp_sfi_managed         :1,                 /* SFI Managed task */
 217             trp_qos_clamp           :3,                 /* task qos clamp */
 218
 219         /* suppression policies (non-embedded only) */
 220             trp_sup_active          :1,                 /* Suppression is on */
 221             trp_sup_lowpri_cpu      :1,                 /* Wants low priority CPU (MAXPRI_THROTTLE) */
 222             trp_sup_timer           :3,                 /* Wanted timer throttling QoS tier */
 223             trp_sup_disk            :1,                 /* Wants disk throttling */
 224             trp_sup_throughput      :3,                 /* Wants throughput QoS tier */
 225             trp_sup_cpu             :1,                 /* Wants suppressed CPU priority (MAXPRI_SUPPRESSED) */
 226             trp_sup_bg_sockets      :1,                 /* Wants background sockets */
 227
 228             trp_reserved            :17;
 229 };
 230
 231 struct task_effective_policy {
 232         uint64_t        tep_darwinbg            :1,     /* marked as 'background', and sockets are marked bg when created */
 233             tep_lowpri_cpu          :1,                 /* cpu priority == MAXPRI_THROTTLE */
 234             tep_io_tier             :2,                 /* effective throttle tier */
 235             tep_io_passive          :1,                 /* should IOs cause lower tiers to be throttled */
 236             tep_all_sockets_bg      :1,                 /* All existing sockets in process are marked as bg (thread: all created by thread) */
 237             tep_new_sockets_bg      :1,                 /* Newly created sockets should be marked as bg */
 238             tep_bg_iotier           :2,                 /* What throttle tier should I be in when darwinbg is set? */
 239             tep_terminated          :1,                 /* all throttles have been removed for quick exit or SIGTERM handling */
 240             tep_qos_ui_is_urgent    :1,                 /* bump UI-Interactive QoS up to the urgent preemption band */
 241             tep_latency_qos         :3,                 /* Timer latency QoS level */
 242             tep_through_qos         :3,                 /* Computation throughput QoS level */
 243
 244             tep_tal_engaged         :1,                 /* TAL mode is in effect */
 245             tep_watchers_bg         :1,                 /* watchers are BG-ed */
 246             tep_sup_active          :1,                 /* suppression behaviors are in effect */
 247             tep_role                :4,                 /* task's system role */
 248             tep_suppressed_cpu      :1,                 /* cpu priority == MAXPRI_SUPPRESSED (trumped by lowpri_cpu) */
 249             tep_sfi_managed         :1,                 /* SFI Managed task */
 250             tep_live_donor          :1,                 /* task is a live importance boost donor */
 251             tep_qos_clamp           :3,                 /* task qos clamp (applies to qos-disabled threads too) */
 252             tep_qos_ceiling         :3,                 /* task qos ceiling (applies to only qos-participating threads) */
 253
 254             tep_reserved            :31;
 255 };
 256
 257 #endif /* PRIVATE */
 258
 259 #ifdef MACH_KERNEL_PRIVATE
 260
 261 extern const struct task_requested_policy default_task_requested_policy;
 262 extern const struct task_effective_policy default_task_effective_policy;
 263
 264 extern kern_return_t
 265     qos_latency_policy_validate(task_latency_qos_t);
 266
 267 extern kern_return_t
 268     qos_throughput_policy_validate(task_throughput_qos_t);
 269
 270 extern uint32_t
 271     qos_extract(uint32_t);
 272
 273 extern uint32_t
 274     qos_latency_policy_package(uint32_t);
 275 extern uint32_t
 276     qos_throughput_policy_package(uint32_t);
 277
 278 #endif /* MACH_KERNEL_PRIVATE */
 279
 280 #ifdef PRIVATE
 281
 282 /*
 283  * Control structure for applying suppression behaviors to tasks
 284  */
 285 struct task_suppression_policy {
 286         integer_t active;
 287         integer_t lowpri_cpu;  /* priority MAXPRI_THROTTLE cpu */
 288         integer_t timer_throttle;
 289         integer_t disk_throttle;
 290         integer_t cpu_limit;
 291         integer_t suspend;
 292         integer_t throughput_qos;
 293         integer_t suppressed_cpu; /* priority MAXPRI_SUPPRESSED cpu */
 294         integer_t background_sockets;
 295         integer_t reserved[7];
 296 };
 297
 298 typedef struct task_suppression_policy *task_suppression_policy_t;
 299
 300 #define TASK_SUPPRESSION_POLICY_COUNT   ((mach_msg_type_number_t) \
 301         (sizeof (struct task_suppression_policy) / sizeof (integer_t)))
 302
 303 struct task_policy_state {
 304         uint64_t requested;
 305         uint64_t effective;
 306         uint64_t pending;
 307         uint32_t imp_assertcnt;
 308         uint32_t imp_externcnt;
 309         uint64_t flags;
 310         uint64_t imp_transitions;
 311         uint64_t tps_requested_policy;
 312         uint64_t tps_effective_policy;
 313 };
 314
 315 typedef struct task_policy_state *task_policy_state_t;
 316
 317 #define TASK_POLICY_STATE_COUNT ((mach_msg_type_number_t) \
 318         (sizeof (struct task_policy_state) / sizeof (integer_t)))
 319
 320
 321 /*
 322  * Definitions for munging and unmunging a policy struct
 323  * Used in task_policy_state and in tracepoints
 324  *
 325  * Note: this is tightly bound to the implementation of task policy
 326  * and the values exported through this API may change or change meaning at any time
 327  *
 328  * Do not rely on these values, especially apptype, to decide behaviors at runtime.
 329  *
 330  * All per-thread state must be in the first 32 bits of the bitfield.
 331  */
 332
 333 #define TASK_APPTYPE_NONE                0
 334 #define TASK_APPTYPE_DAEMON_INTERACTIVE  1
 335 #define TASK_APPTYPE_DAEMON_STANDARD     2
 336 #define TASK_APPTYPE_DAEMON_ADAPTIVE     3
 337 #define TASK_APPTYPE_DAEMON_BACKGROUND   4
 338 #define TASK_APPTYPE_APP_DEFAULT         5
 339 #define TASK_APPTYPE_APP_TAL             6
 340 #define TASK_APPTYPE_DRIVER              7
 341
 342 /* task policy state flags */
 343 #define TASK_IMP_RECEIVER                    0x00000001
 344 #define TASK_IMP_DONOR                       0x00000002
 345 #define TASK_IMP_LIVE_DONOR                  0x00000004
 346 #define TASK_DENAP_RECEIVER                  0x00000008
 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_ */