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
 111 enum task_role {
 112         TASK_RENICED = -1,
 113         TASK_UNSPECIFIED = 0,
 114         TASK_FOREGROUND_APPLICATION,
 115         TASK_BACKGROUND_APPLICATION,
 116         TASK_CONTROL_APPLICATION,
 117         TASK_GRAPHICS_SERVER,
 118         TASK_THROTTLE_APPLICATION,
 119         TASK_NONUI_APPLICATION,
 120         TASK_DEFAULT_APPLICATION
 121 };
 122
 123 typedef integer_t       task_role_t;
 124
 125 struct task_category_policy {
 126         task_role_t             role;
 127 };
 128
 129 typedef struct task_category_policy             task_category_policy_data_t;
 130 typedef struct task_category_policy             *task_category_policy_t;
 131
 132 #define TASK_CATEGORY_POLICY_COUNT      ((mach_msg_type_number_t) \
 133         (sizeof (task_category_policy_data_t) / sizeof (integer_t)))
 134
 135
 136 enum task_latency_qos {
 137         LATENCY_QOS_TIER_UNSPECIFIED = 0x0,
 138         LATENCY_QOS_TIER_0 = ((0xFF<<16) | 1),
 139         LATENCY_QOS_TIER_1 = ((0xFF<<16) | 2),
 140         LATENCY_QOS_TIER_2 = ((0xFF<<16) | 3),
 141         LATENCY_QOS_TIER_3 = ((0xFF<<16) | 4),
 142         LATENCY_QOS_TIER_4 = ((0xFF<<16) | 5),
 143         LATENCY_QOS_TIER_5 = ((0xFF<<16) | 6)
 144 };
 145 typedef integer_t       task_latency_qos_t;
 146 enum task_throughput_qos {
 147         THROUGHPUT_QOS_TIER_UNSPECIFIED = 0x0,
 148         THROUGHPUT_QOS_TIER_0 = ((0xFE<<16) | 1),
 149         THROUGHPUT_QOS_TIER_1 = ((0xFE<<16) | 2),
 150         THROUGHPUT_QOS_TIER_2 = ((0xFE<<16) | 3),
 151         THROUGHPUT_QOS_TIER_3 = ((0xFE<<16) | 4),
 152         THROUGHPUT_QOS_TIER_4 = ((0xFE<<16) | 5),
 153         THROUGHPUT_QOS_TIER_5 = ((0xFE<<16) | 6),
 154 };
 155
 156 #define LATENCY_QOS_LAUNCH_DEFAULT_TIER LATENCY_QOS_TIER_3
 157 #define THROUGHPUT_QOS_LAUNCH_DEFAULT_TIER THROUGHPUT_QOS_TIER_3
 158
 159 typedef integer_t       task_throughput_qos_t;
 160
 161 struct task_qos_policy {
 162         task_latency_qos_t task_latency_qos_tier;
 163         task_throughput_qos_t task_throughput_qos_tier;
 164 };
 165
 166 typedef struct task_qos_policy *task_qos_policy_t;
 167 #define TASK_QOS_POLICY_COUNT   ((mach_msg_type_number_t) \
 168         (sizeof (struct task_qos_policy) / sizeof (integer_t)))
 169
 170 #define PROC_FLAG_DARWINBG           0x8000    /* process in darwin background */
 171 #define PROC_FLAG_EXT_DARWINBG           0x10000   /* process in darwin background - external enforcement */
 172 #define PROC_FLAG_IOS_APPLEDAEMON    0x20000   /* process is apple ios daemon */
 173 #define PROC_FLAG_IOS_IMPPROMOTION   0x80000   /* process is apple ios daemon */
 174 #define PROC_FLAG_ADAPTIVE           0x100000  /* Process is adaptive */
 175 #define PROC_FLAG_ADAPTIVE_IMPORTANT 0x200000  /* Process is adaptive, and is currently important */
 176 #define PROC_FLAG_IMPORTANCE_DONOR   0x400000  /* Process is marked as an importance donor */
 177 #define PROC_FLAG_SUPPRESSED         0x800000  /* Process is suppressed */
 178 #define PROC_FLAG_IOS_APPLICATION        0x1000000 /* Process is an application */
 179
 180 #ifdef MACH_KERNEL_PRIVATE
 181
 182 struct task_requested_policy {
 183         /* Task and thread policy (inherited) */
 184         uint64_t        int_darwinbg        :1,     /* marked as darwinbg via setpriority */
 185                         ext_darwinbg        :1,
 186                         int_iotier          :2,     /* IO throttle tier */
 187                         ext_iotier          :2,
 188                         int_iopassive       :1,     /* should IOs cause lower tiers to be throttled */
 189                         ext_iopassive       :1,
 190                         bg_iotier           :2,     /* what IO throttle tier should apply to me when I'm darwinbg? (pushed to threads) */
 191                         terminated          :1,     /* all throttles should be removed for quick exit or SIGTERM handling */
 192
 193         /* Thread only policy */
 194                         th_pidbind_bg       :1,     /* thread only: task i'm bound to is marked 'watchbg' */
 195                         th_workq_bg         :1,     /* thread only: currently running a background priority workqueue */
 196
 197         /* Task only policy */
 198                         t_apptype           :3,     /* What apptype did launchd tell us this was (inherited) */
 199                         t_boosted           :1,     /* Has a non-zero importance assertion count */
 200                         t_int_gpu_deny      :1,     /* don't allow access to GPU */
 201                         t_ext_gpu_deny      :1,
 202                         t_role              :3,     /* task's system role */
 203                         t_tal_enabled       :1,     /* TAL mode is enabled */
 204                         t_base_latency_qos  :3,     /* Timer latency QoS */
 205                         t_over_latency_qos  :3,     /* Timer latency QoS override */
 206                         t_base_through_qos  :3,     /* Computation throughput QoS */
 207                         t_over_through_qos  :3,     /* Computation throughput QoS override */
 208
 209         /* Task only: suppression policies (non-embedded only) */
 210                         t_sup_active        :1,     /* Suppression is on */
 211                         t_sup_lowpri_cpu    :1,     /* Wants low priority CPU (MAXPRI_THROTTLE) */
 212                         t_sup_timer         :3,     /* Wanted timer throttling QoS tier */
 213                         t_sup_disk          :1,     /* Wants disk throttling */
 214                         t_sup_cpu_limit     :1,     /* Wants CPU limit (not hooked up yet)*/
 215                         t_sup_suspend       :1,     /* Wants to be suspended */
 216                         t_sup_throughput    :3,     /* Wants throughput QoS tier */
 217                         t_sup_cpu           :1,     /* Wants suppressed CPU priority (MAXPRI_SUPPRESSED) */
 218
 219                         reserved            :17;
 220 };
 221
 222 struct task_effective_policy {
 223         /* Task and thread policy */
 224         uint64_t        darwinbg            :1,     /* marked as 'background', and sockets are marked bg when created */
 225                         lowpri_cpu          :1,     /* cpu priority == MAXPRI_THROTTLE */
 226                         io_tier             :2,     /* effective throttle tier */
 227                         io_passive          :1,     /* should IOs cause lower tiers to be throttled */
 228                         all_sockets_bg      :1,     /* All existing sockets in process are marked as bg (thread: all created by thread) */
 229                         new_sockets_bg      :1,     /* Newly created sockets should be marked as bg */
 230                         bg_iotier           :2,     /* What throttle tier should I be in when darwinbg is set? */
 231                         terminated          :1,     /* all throttles have been removed for quick exit or SIGTERM handling */
 232
 233         /* Task only policy */
 234                         t_gpu_deny          :1,     /* not allowed to access GPU */
 235                         t_tal_engaged       :1,     /* TAL mode is in effect */
 236                         t_suspended         :1,     /* task_suspend-ed due to suppression */
 237                         t_watchers_bg       :1,     /* watchers are BG-ed */
 238                         t_latency_qos       :3,     /* Timer latency QoS level */
 239                         t_through_qos       :3,     /* Computation throughput QoS level */
 240                         t_sup_active        :1,     /* suppression behaviors are in effect */
 241                         t_role              :3,     /* task's system role */
 242                         t_suppressed_cpu    :1,     /* cpu priority == MAXPRI_SUPPRESSED (trumped by lowpri_cpu) */
 243
 244                         reserved            :39;
 245 };
 246
 247 struct task_pended_policy {
 248         uint64_t        t_updating_policy   :1,     /* Busy bit for task to prevent concurrent 'complete' operations */
 249
 250         /* Task and thread policy */
 251                         update_sockets      :1,
 252
 253         /* Task only policy */
 254                         t_update_timers     :1,
 255                         t_update_watchers   :1,
 256
 257                         reserved            :60;
 258 };
 259
 260 extern const struct task_requested_policy default_task_requested_policy;
 261 extern const struct task_effective_policy default_task_effective_policy;
 262 extern const struct task_pended_policy    default_task_pended_policy;
 263
 264
 265 #endif /* MACH_KERNEL_PRIVATE */
 266
 267 #ifdef PRIVATE
 268
 269 /*
 270  * Control structure for applying suppression behaviors to tasks
 271  */
 272 struct task_suppression_policy {
 273         integer_t active;
 274         integer_t lowpri_cpu;  /* priority MAXPRI_THROTTLE cpu */
 275         integer_t timer_throttle;
 276         integer_t disk_throttle;
 277         integer_t cpu_limit;
 278         integer_t suspend;
 279         integer_t throughput_qos;
 280         integer_t suppressed_cpu; /* priority MAXPRI_SUPPRESSED cpu */
 281         integer_t reserved[8];
 282 };
 283
 284 typedef struct task_suppression_policy *task_suppression_policy_t;
 285
 286 #define TASK_SUPPRESSION_POLICY_COUNT   ((mach_msg_type_number_t) \
 287         (sizeof (struct task_suppression_policy) / sizeof (integer_t)))
 288
 289 struct task_policy_state {
 290         uint64_t requested;
 291         uint64_t effective;
 292         uint64_t pending;
 293         uint32_t imp_assertcnt;
 294         uint32_t imp_externcnt;
 295         uint64_t flags;
 296         uint64_t reserved[3];
 297 };
 298
 299 typedef struct task_policy_state *task_policy_state_t;
 300
 301 #define TASK_POLICY_STATE_COUNT ((mach_msg_type_number_t) \
 302         (sizeof (struct task_policy_state) / sizeof (integer_t)))
 303
 304
 305 /*
 306  * Definitions for munging and unmunging a policy struct
 307  * Used in task_policy_state and in tracepoints
 308  *
 309  * Note: this is tightly bound to the implementation of task policy
 310  * and the values exported through this API may change or change meaning at any time
 311  *
 312  * Do not rely on these values, especially apptype, to decide behaviors at runtime.
 313  *
 314  * All per-thread state must be in the first 32 bits of the bitfield.
 315  */
 316
 317 #define TASK_APPTYPE_NONE                0
 318 #define TASK_APPTYPE_DAEMON_INTERACTIVE  1
 319 #define TASK_APPTYPE_DAEMON_STANDARD     2
 320 #define TASK_APPTYPE_DAEMON_ADAPTIVE     3
 321 #define TASK_APPTYPE_DAEMON_BACKGROUND   4
 322 #define TASK_APPTYPE_APP_DEFAULT         5
 323 #define TASK_APPTYPE_APP_TAL             6
 324
 325 /* task policy state flags */
 326 #define TASK_IMP_RECEIVER                    0x00000001
 327 #define TASK_IMP_DONOR                       0x00000002
 328
 329 /* requested_policy */
 330 #define POLICY_REQ_INT_DARWIN_BG             0x00000001
 331 #define POLICY_REQ_EXT_DARWIN_BG             0x00000002
 332 #define POLICY_REQ_INT_IO_TIER_MASK          0x0000000c /* 2 bits */
 333 #define POLICY_REQ_INT_IO_TIER_SHIFT         2
 334 #define POLICY_REQ_EXT_IO_TIER_MASK          0x00000030 /* 2 bits */
 335 #define POLICY_REQ_EXT_IO_TIER_SHIFT         4
 336 #define POLICY_REQ_INT_PASSIVE_IO            0x00000040
 337 #define POLICY_REQ_EXT_PASSIVE_IO            0x00000080
 338 #define POLICY_REQ_BG_IOTIER_MASK            0x00000300 /* 2 bits */
 339 #define POLICY_REQ_BG_IOTIER_SHIFT           8
 340 #define POLICY_REQ_PIDBIND_BG                0x00000400
 341 #define POLICY_REQ_WORKQ_BG                  0x00000800
 342
 343 /* task_requested_policy */
 344 #define POLICY_REQ_TERMINATED                0x00001000
 345 #define POLICY_REQ_BOOSTED                   0x00002000
 346 #define POLICY_REQ_INT_GPU_DENY              0x00004000
 347 #define POLICY_REQ_EXT_GPU_DENY              0x00008000
 348 #define POLICY_REQ_APPTYPE_MASK              0x00070000 /* 3 bits */
 349 #define POLICY_REQ_APPTYPE_SHIFT             16
 350 #define POLICY_REQ_BASE_LATENCY_QOS_MASK     0x00700000 /* 3 bits */
 351 #define POLICY_REQ_BASE_LATENCY_QOS_SHIFT    20
 352 #define POLICY_REQ_ROLE_MASK                 0x07000000 /* 3 bits */
 353 #define POLICY_REQ_ROLE_SHIFT                24
 354 #define POLICY_REQ_TAL_ENABLED               0x40000000
 355
 356 /* requested suppression behaviors (note: clipped off in 32-bit tracepoints) */
 357 #define POLICY_REQ_SUP_ACTIVE                0x0000000100000000
 358 #define POLICY_REQ_SUP_LOWPRI_CPU            0x0000000200000000
 359 #define POLICY_REQ_SUP_CPU                   0x0000000400000000
 360 #define POLICY_REQ_SUP_DISK_THROTTLE         0x0000003000000000 /* 2 bits */
 361 #define POLICY_REQ_SUP_CPU_LIMIT             0x0000004000000000
 362 #define POLICY_REQ_SUP_SUSPEND               0x0000008000000000
 363 #define POLICY_REQ_OVER_LATENCY_QOS_MASK     0x0000070000000000 /* 3 bits */
 364 #define POLICY_REQ_OVER_LATENCY_QOS_SHIFT    40
 365 #define POLICY_REQ_BASE_THROUGH_QOS_MASK     0x0000700000000000 /* 3 bits */
 366 #define POLICY_REQ_BASE_THROUGH_QOS_SHIFT    44
 367 #define POLICY_REQ_OVER_THROUGH_QOS_MASK     0x0007000000000000 /* 3 bits */
 368 #define POLICY_REQ_OVER_THROUGH_QOS_SHIFT    48
 369 #define POLICY_REQ_SUP_TIMER_THROTTLE_MASK   0x0070000000000000 /* 3 bits */
 370 #define POLICY_REQ_SUP_TIMER_THROTTLE_SHIFT  52
 371 #define POLICY_REQ_SUP_THROUGHPUT_MASK       0x0700000000000000 /* 3 bits */
 372 #define POLICY_REQ_SUP_THROUGHPUT_SHIFT      56
 373
 374 /* effective policy */
 375 #define POLICY_EFF_IO_TIER_MASK              0x00000003 /* 2 bits */
 376 #define POLICY_EFF_IO_TIER_SHIFT             0
 377 #define POLICY_EFF_IO_PASSIVE                0x00000008
 378 #define POLICY_EFF_DARWIN_BG                 0x00000010
 379 #define POLICY_EFF_LOWPRI_CPU                0x00000020
 380 #define POLICY_EFF_ALL_SOCKETS_BG            0x00000040
 381 #define POLICY_EFF_NEW_SOCKETS_BG            0x00000080
 382 #define POLICY_EFF_BG_IOTIER_MASK            0x00000300 /* 2 bits */
 383 #define POLICY_EFF_BG_IOTIER_SHIFT           8
 384 #define POLICY_EFF_TERMINATED                0x00000400
 385
 386 /* task effective policy */
 387 #define POLICY_EFF_GPU_DENY                  0x00001000
 388 #define POLICY_EFF_TAL_ENGAGED               0x00002000
 389 #define POLICY_EFF_SUSPENDED                 0x00004000
 390 #define POLICY_EFF_WATCHERS_BG               0x00008000
 391 #define POLICY_EFF_LATENCY_QOS_MASK          0x00070000 /* 3 bits */
 392 #define POLICY_EFF_LATENCY_QOS_SHIFT         16
 393 #define POLICY_EFF_SUP_ACTIVE                0x00080000
 394 #define POLICY_EFF_ROLE_MASK                 0x00700000 /* 3 bits */
 395 #define POLICY_EFF_ROLE_SHIFT                20
 396 #define POLICY_EFF_SUP_CPU                   0x00800000
 397 #define POLICY_EFF_THROUGH_QOS_MASK          0x07000000 /* 3 bits */
 398 #define POLICY_EFF_THROUGH_QOS_SHIFT         24
 399
 400 /* pending policy */
 401 #define POLICY_PEND_UPDATING                 0x00000001
 402 #define POLICY_PEND_SOCKETS                  0x00000002
 403 #define POLICY_PEND_TIMERS                   0x00000004
 404 #define POLICY_PEND_WATCHERS                 0x00000008
 405
 406 #endif /* PRIVATE */
 407
 408 #endif  /* _MACH_TASK_POLICY_H_ */