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#define TASK_BASE_LATENCY_QOS_POLICY 10 111#define TASK_BASE_THROUGHPUT_QOS_POLICY 11 112 113 114enum task_role { 115 TASK_RENICED = -1, 116 TASK_UNSPECIFIED = 0, 117 TASK_FOREGROUND_APPLICATION, 118 TASK_BACKGROUND_APPLICATION, 119 TASK_CONTROL_APPLICATION, 120 TASK_GRAPHICS_SERVER, 121 TASK_THROTTLE_APPLICATION, 122 TASK_NONUI_APPLICATION, 123 TASK_DEFAULT_APPLICATION 124}; 125 126typedef integer_t task_role_t; 127 128struct task_category_policy { 129 task_role_t role; 130}; 131 132typedef struct task_category_policy task_category_policy_data_t; 133typedef struct task_category_policy *task_category_policy_t; 134 135#define TASK_CATEGORY_POLICY_COUNT ((mach_msg_type_number_t) \ 136 (sizeof (task_category_policy_data_t) / sizeof (integer_t))) 137 138 139enum task_latency_qos { 140 LATENCY_QOS_TIER_UNSPECIFIED = 0x0, 141 LATENCY_QOS_TIER_0 = ((0xFF<<16) | 1), 142 LATENCY_QOS_TIER_1 = ((0xFF<<16) | 2), 143 LATENCY_QOS_TIER_2 = ((0xFF<<16) | 3), 144 LATENCY_QOS_TIER_3 = ((0xFF<<16) | 4), 145 LATENCY_QOS_TIER_4 = ((0xFF<<16) | 5), 146 LATENCY_QOS_TIER_5 = ((0xFF<<16) | 6) 147 148}; 149typedef integer_t task_latency_qos_t; 150enum 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 163typedef integer_t task_throughput_qos_t; 164 165struct task_qos_policy { 166 task_latency_qos_t task_latency_qos_tier; 167 task_throughput_qos_t task_throughput_qos_tier; 168}; 169 170typedef 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 188struct task_requested_policy { 189 /* Task and thread policy (inherited) */ 190 uint64_t int_darwinbg :1, /* marked as darwinbg via setpriority */ 191 ext_darwinbg :1, 192 int_iotier :2, /* IO throttle tier */ 193 ext_iotier :2, 194 int_iopassive :1, /* should IOs cause lower tiers to be throttled */ 195 ext_iopassive :1, 196 bg_iotier :2, /* what IO throttle tier should apply to me when I'm darwinbg? (pushed to threads) */ 197 terminated :1, /* all throttles should be removed for quick exit or SIGTERM handling */ 198 199 /* Thread only policy */ 200 th_pidbind_bg :1, /* thread only: task i'm bound to is marked 'watchbg' */ 201 th_workq_bg :1, /* thread only: currently running a background priority workqueue */ 202 thrp_qos :3, /* thread only: thread qos class */ 203 thrp_qos_relprio :4, /* thread only: thread qos relative priority (store as inverse, -10 -> 0xA) */ 204 thrp_qos_override :3, /* thread only: thread qos class override */ 205 206 /* Task only policy */ 207 t_apptype :3, /* What apptype did launchd tell us this was (inherited) */ 208 t_boosted :1, /* Has a non-zero importance assertion count */ 209 t_int_gpu_deny :1, /* don't allow access to GPU */ 210 t_ext_gpu_deny :1, 211 t_role :3, /* task's system role */ 212 t_tal_enabled :1, /* TAL mode is enabled */ 213 t_base_latency_qos :3, /* Timer latency QoS */ 214 t_over_latency_qos :3, /* Timer latency QoS override */ 215 t_base_through_qos :3, /* Computation throughput QoS */ 216 t_over_through_qos :3, /* Computation throughput QoS override */ 217 t_sfi_managed :1, /* SFI Managed task */ 218 t_qos_clamp :3, /* task qos clamp */ 219 220 /* Task only: suppression policies (non-embedded only) */ 221 t_sup_active :1, /* Suppression is on */ 222 t_sup_lowpri_cpu :1, /* Wants low priority CPU (MAXPRI_THROTTLE) */ 223 t_sup_timer :3, /* Wanted timer throttling QoS tier */ 224 t_sup_disk :1, /* Wants disk throttling */ 225 t_sup_cpu_limit :1, /* Wants CPU limit (not hooked up yet)*/ 226 t_sup_suspend :1, /* Wants to be suspended */ 227 t_sup_throughput :3, /* Wants throughput QoS tier */ 228 t_sup_cpu :1, /* Wants suppressed CPU priority (MAXPRI_SUPPRESSED) */ 229 t_sup_bg_sockets :1, /* Wants background sockets */ 230 231 reserved :2; 232}; 233 234struct task_effective_policy { 235 /* Task and thread policy */ 236 uint64_t darwinbg :1, /* marked as 'background', and sockets are marked bg when created */ 237 lowpri_cpu :1, /* cpu priority == MAXPRI_THROTTLE */ 238 io_tier :2, /* effective throttle tier */ 239 io_passive :1, /* should IOs cause lower tiers to be throttled */ 240 all_sockets_bg :1, /* All existing sockets in process are marked as bg (thread: all created by thread) */ 241 new_sockets_bg :1, /* Newly created sockets should be marked as bg */ 242 bg_iotier :2, /* What throttle tier should I be in when darwinbg is set? */ 243 terminated :1, /* all throttles have been removed for quick exit or SIGTERM handling */ 244 qos_ui_is_urgent :1, /* bump UI-Interactive QoS up to the urgent preemption band */ 245 246 /* Thread only policy */ 247 thep_qos :3, /* thread only: thread qos class */ 248 thep_qos_relprio :4, /* thread only: thread qos relative priority (store as inverse, -10 -> 0xA) */ 249 250 /* Task only policy */ 251 t_gpu_deny :1, /* not allowed to access GPU */ 252 t_tal_engaged :1, /* TAL mode is in effect */ 253 t_suspended :1, /* task_suspend-ed due to suppression */ 254 t_watchers_bg :1, /* watchers are BG-ed */ 255 t_latency_qos :3, /* Timer latency QoS level */ 256 t_through_qos :3, /* Computation throughput QoS level */ 257 t_sup_active :1, /* suppression behaviors are in effect */ 258 t_role :3, /* task's system role */ 259 t_suppressed_cpu :1, /* cpu priority == MAXPRI_SUPPRESSED (trumped by lowpri_cpu) */ 260 t_sfi_managed :1, /* SFI Managed task */ 261 t_live_donor :1, /* task is a live importance boost donor */ 262 t_qos_clamp :3, /* task qos clamp (applies to qos-disabled threads too) */ 263 t_qos_ceiling :3, /* task qos ceiling (applies to only qos-participating threads) */ 264 265 reserved :23; 266}; 267 268struct task_pended_policy { 269 uint64_t t_updating_policy :1, /* Busy bit for task to prevent concurrent 'complete' operations */ 270 271 /* Task and thread policy */ 272 update_sockets :1, 273 274 /* Task only policy */ 275 t_update_timers :1, 276 t_update_watchers :1, 277 278 reserved :60; 279}; 280 281#endif 282 283#ifdef MACH_KERNEL_PRIVATE 284 285extern const struct task_requested_policy default_task_requested_policy; 286extern const struct task_effective_policy default_task_effective_policy; 287extern const struct task_pended_policy default_task_pended_policy; 288 289extern kern_return_t 290qos_latency_policy_validate(task_latency_qos_t); 291 292extern kern_return_t 293qos_throughput_policy_validate(task_throughput_qos_t); 294 295extern uint32_t 296qos_extract(uint32_t); 297 298extern uint32_t 299qos_latency_policy_package(uint32_t); 300extern uint32_t 301qos_throughput_policy_package(uint32_t); 302 303#endif /* MACH_KERNEL_PRIVATE */ 304 305#ifdef PRIVATE 306 307/* 308 * Control structure for applying suppression behaviors to tasks 309 */ 310struct task_suppression_policy { 311 integer_t active; 312 integer_t lowpri_cpu; /* priority MAXPRI_THROTTLE cpu */ 313 integer_t timer_throttle; 314 integer_t disk_throttle; 315 integer_t cpu_limit; 316 integer_t suspend; 317 integer_t throughput_qos; 318 integer_t suppressed_cpu; /* priority MAXPRI_SUPPRESSED cpu */ 319 integer_t background_sockets; 320 integer_t reserved[7]; 321}; 322 323typedef struct task_suppression_policy *task_suppression_policy_t; 324 325#define TASK_SUPPRESSION_POLICY_COUNT ((mach_msg_type_number_t) \ 326 (sizeof (struct task_suppression_policy) / sizeof (integer_t))) 327 328struct task_policy_state { 329 uint64_t requested; 330 uint64_t effective; 331 uint64_t pending; 332 uint32_t imp_assertcnt; 333 uint32_t imp_externcnt; 334 uint64_t flags; 335 uint64_t imp_transitions; 336 uint64_t reserved[2]; 337}; 338 339typedef struct task_policy_state *task_policy_state_t; 340 341#define TASK_POLICY_STATE_COUNT ((mach_msg_type_number_t) \ 342 (sizeof (struct task_policy_state) / sizeof (integer_t))) 343 344 345/* 346 * Definitions for munging and unmunging a policy struct 347 * Used in task_policy_state and in tracepoints 348 * 349 * Note: this is tightly bound to the implementation of task policy 350 * and the values exported through this API may change or change meaning at any time 351 * 352 * Do not rely on these values, especially apptype, to decide behaviors at runtime. 353 * 354 * All per-thread state must be in the first 32 bits of the bitfield. 355 */ 356 357#define TASK_APPTYPE_NONE 0 358#define TASK_APPTYPE_DAEMON_INTERACTIVE 1 359#define TASK_APPTYPE_DAEMON_STANDARD 2 360#define TASK_APPTYPE_DAEMON_ADAPTIVE 3 361#define TASK_APPTYPE_DAEMON_BACKGROUND 4 362#define TASK_APPTYPE_APP_DEFAULT 5 363#define TASK_APPTYPE_APP_TAL 6 364 365/* task policy state flags */ 366#define TASK_IMP_RECEIVER 0x00000001 367#define TASK_IMP_DONOR 0x00000002 368#define TASK_IMP_LIVE_DONOR 0x00000004 369#define TASK_DENAP_RECEIVER 0x00000008 370 371/* requested_policy */ 372#define POLICY_REQ_INT_DARWIN_BG 0x00000001 373#define POLICY_REQ_EXT_DARWIN_BG 0x00000002 374#define POLICY_REQ_INT_IO_TIER_MASK 0x0000000c /* 2 bits */ 375#define POLICY_REQ_INT_IO_TIER_SHIFT 2 376#define POLICY_REQ_EXT_IO_TIER_MASK 0x00000030 /* 2 bits */ 377#define POLICY_REQ_EXT_IO_TIER_SHIFT 4 378#define POLICY_REQ_INT_PASSIVE_IO 0x00000040 379#define POLICY_REQ_EXT_PASSIVE_IO 0x00000080 380#define POLICY_REQ_BG_IOTIER_MASK 0x00000300 /* 2 bits */ 381#define POLICY_REQ_BG_IOTIER_SHIFT 8 382 383/* thread requested policy */ 384#define POLICY_REQ_PIDBIND_BG 0x00000400 385#define POLICY_REQ_WORKQ_BG 0x00000800 386#define POLICY_REQ_TH_QOS_MASK 0x07000000 /* 3 bits (overlaps with ROLE) */ 387#define POLICY_REQ_TH_QOS_SHIFT 24 388#define POLICY_REQ_TH_QOS_OVER_MASK 0x70000000 /* 3 bits (overlaps with TAL and SFI) */ 389#define POLICY_REQ_TH_QOS_OVER_SHIFT 28 390 391/* task_requested_policy */ 392#define POLICY_REQ_TERMINATED 0x00001000 393#define POLICY_REQ_BOOSTED 0x00002000 394#define POLICY_REQ_INT_GPU_DENY 0x00004000 395#define POLICY_REQ_EXT_GPU_DENY 0x00008000 396#define POLICY_REQ_APPTYPE_MASK 0x00070000 /* 3 bits */ 397#define POLICY_REQ_APPTYPE_SHIFT 16 398#define POLICY_REQ_BASE_LATENCY_QOS_MASK 0x00700000 /* 3 bits */ 399#define POLICY_REQ_BASE_LATENCY_QOS_SHIFT 20 400#define POLICY_REQ_ROLE_MASK 0x07000000 /* 3 bits */ 401#define POLICY_REQ_ROLE_SHIFT 24 402#define POLICY_REQ_TAL_ENABLED 0x40000000 403#define POLICY_REQ_SFI_MANAGED 0x80000000 404 405/* requested suppression behaviors (note: clipped off in 32-bit tracepoints) */ 406#define POLICY_REQ_SUP_ACTIVE 0x0000000100000000 407#define POLICY_REQ_SUP_LOWPRI_CPU 0x0000000200000000 408#define POLICY_REQ_SUP_CPU 0x0000000400000000 409#define POLICY_REQ_SUP_DISK_THROTTLE 0x0000003000000000 /* 2 bits */ 410#define POLICY_REQ_SUP_CPU_LIMIT 0x0000004000000000 411#define POLICY_REQ_SUP_SUSPEND 0x0000008000000000 412#define POLICY_REQ_OVER_LATENCY_QOS_MASK 0x0000070000000000 /* 3 bits */ 413#define POLICY_REQ_OVER_LATENCY_QOS_SHIFT 40 414#define POLICY_REQ_BASE_THROUGH_QOS_MASK 0x0000700000000000 /* 3 bits */ 415#define POLICY_REQ_BASE_THROUGH_QOS_SHIFT 44 416#define POLICY_REQ_OVER_THROUGH_QOS_MASK 0x0007000000000000 /* 3 bits */ 417#define POLICY_REQ_OVER_THROUGH_QOS_SHIFT 48 418#define POLICY_REQ_SUP_TIMER_THROTTLE_MASK 0x0070000000000000 /* 3 bits */ 419#define POLICY_REQ_SUP_TIMER_THROTTLE_SHIFT 52 420#define POLICY_REQ_SUP_THROUGHPUT_MASK 0x0700000000000000 /* 3 bits */ 421#define POLICY_REQ_SUP_THROUGHPUT_SHIFT 56 422#define POLICY_REQ_SUP_BG_SOCKETS 0x0800008000000000 423#define POLICY_REQ_QOS_CLAMP_MASK 0x7000000000000000 /* 3 bits */ 424#define POLICY_REQ_QOS_CLAMP_SHIFT 60 425 426/* effective policy */ 427#define POLICY_EFF_IO_TIER_MASK 0x00000003 /* 2 bits */ 428#define POLICY_EFF_IO_TIER_SHIFT 0 429#define POLICY_EFF_IO_PASSIVE 0x00000008 430#define POLICY_EFF_DARWIN_BG 0x00000010 431#define POLICY_EFF_LOWPRI_CPU 0x00000020 432#define POLICY_EFF_ALL_SOCKETS_BG 0x00000040 433#define POLICY_EFF_NEW_SOCKETS_BG 0x00000080 434#define POLICY_EFF_BG_IOTIER_MASK 0x00000300 /* 2 bits */ 435#define POLICY_EFF_BG_IOTIER_SHIFT 8 436#define POLICY_EFF_TERMINATED 0x00000400 437#define POLICY_EFF_QOS_UI_IS_URGENT 0x80000000 438 439/* thread effective policy */ 440#define POLICY_EFF_TH_QOS_MASK 0x00700000 /* 3 bits (overlaps with ROLE) */ 441#define POLICY_EFF_TH_QOS_SHIFT 20 442#define POLICY_EFF_LATENCY_QOS_MASK 0x00070000 /* 3 bits */ 443#define POLICY_EFF_LATENCY_QOS_SHIFT 16 444#define POLICY_EFF_THROUGH_QOS_MASK 0x07000000 /* 3 bits */ 445#define POLICY_EFF_THROUGH_QOS_SHIFT 24 446 447/* task effective policy */ 448#define POLICY_EFF_GPU_DENY 0x00001000 449#define POLICY_EFF_TAL_ENGAGED 0x00002000 450#define POLICY_EFF_SUSPENDED 0x00004000 451#define POLICY_EFF_WATCHERS_BG 0x00008000 452#define POLICY_EFF_SUP_ACTIVE 0x00080000 453#define POLICY_EFF_ROLE_MASK 0x00700000 /* 3 bits */ 454#define POLICY_EFF_ROLE_SHIFT 20 455#define POLICY_EFF_SUP_CPU 0x00800000 456#define POLICY_EFF_SFI_MANAGED 0x08000000 457#define POLICY_EFF_QOS_CEILING_MASK 0x70000000 458#define POLICY_EFF_QOS_CEILING_SHIFT 28 459 460/* pending policy */ 461#define POLICY_PEND_UPDATING 0x00000001 462#define POLICY_PEND_SOCKETS 0x00000002 463#define POLICY_PEND_TIMERS 0x00000004 464#define POLICY_PEND_WATCHERS 0x00000008 465 466#endif /* PRIVATE */ 467 468#endif /* _MACH_TASK_POLICY_H_ */ 469