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 51typedef natural_t task_policy_flavor_t; 52typedef integer_t *task_policy_t; 53 54/* 55kern_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 61kern_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 111enum 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 123typedef integer_t task_role_t; 124 125struct task_category_policy { 126 task_role_t role; 127}; 128 129typedef struct task_category_policy task_category_policy_data_t; 130typedef 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 136enum 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}; 145typedef integer_t task_latency_qos_t; 146enum 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 159typedef integer_t task_throughput_qos_t; 160 161struct task_qos_policy { 162 task_latency_qos_t task_latency_qos_tier; 163 task_throughput_qos_t task_throughput_qos_tier; 164}; 165 166typedef 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 182struct 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 222struct 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 247struct 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 260extern const struct task_requested_policy default_task_requested_policy; 261extern const struct task_effective_policy default_task_effective_policy; 262extern 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 */ 272struct 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 284typedef 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 289struct 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 299typedef 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_ */ 409