1/*
2 * Copyright (c) 2016 Apple 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/*
30 * Thread group support routines.
31 */
32#ifndef _KERN_THREAD_GROUP_H_
33#define _KERN_THREAD_GROUP_H_
34
35struct thread_group;
36
37#include <mach/thread_status.h> /* for proc_reg.h / CONFIG_THREAD_GROUPS */
38
39#ifndef CONFIG_THREAD_GROUPS
40#error "The platform must define CONFIG_THREAD_GROUPS to 0 or 1"
41#endif
42
43#if CONFIG_THREAD_GROUPS
44#include <kern/assert.h>
45#include <kern/queue.h>
46#include <machine/machine_routines.h>
47
48#define THREAD_GROUP_MAX (CONFIG_TASK_MAX + 10)
49#define THREAD_GROUP_MAXNAME (32)
50
51#define THREAD_GROUP_SYSTEM 0 // kernel (-VM) + launchd
52#define THREAD_GROUP_BACKGROUND 1 // background daemons
53#define THREAD_GROUP_VM 3 // kernel VM threads
54#define THREAD_GROUP_IO_STORAGE 4 // kernel io storage threads
55#define THREAD_GROUP_PERF_CONTROLLER 5 // kernel CLPC threads
56
57#define THREAD_GROUP_INVALID UINT64_MAX
58
59/* Thread group flags */
60
61/* Flags in the bottom 8 bits are exclusive. */
62#define THREAD_GROUP_EXCLUSIVE_FLAGS_MASK 0xff
63
64/* Exclusive flags */
65#define THREAD_GROUP_FLAGS_DEFAULT 0x0
66#define THREAD_GROUP_FLAGS_EFFICIENT 0x1
67#define THREAD_GROUP_FLAGS_APPLICATION 0x2
68#define THREAD_GROUP_FLAGS_CRITICAL 0x4
69#define THREAD_GROUP_FLAGS_BEST_EFFORT 0x8
70
71/* Shared flags */
72#define THREAD_GROUP_FLAGS_UI_APP 0x100
73#define THREAD_GROUP_FLAGS_MANAGED 0x200
74#define THREAD_GROUP_FLAGS_STRICT_TIMERS 0x400
75#define THREAD_GROUP_FLAGS_GAME_MODE 0x800
76
77
78#define THREAD_GROUP_FLAGS_EXCLUSIVE ( \
79 THREAD_GROUP_FLAGS_EFFICIENT | \
80 THREAD_GROUP_FLAGS_APPLICATION | \
81 THREAD_GROUP_FLAGS_CRITICAL | \
82 THREAD_GROUP_FLAGS_BEST_EFFORT)
83
84#define THREAD_GROUP_FLAGS_ABSENT 0xffffffff
85
86static_assert(
87 (THREAD_GROUP_FLAGS_EXCLUSIVE & ~THREAD_GROUP_EXCLUSIVE_FLAGS_MASK) == 0,
88 "valid exclusive flags");
89
90/* Shared flags */
91#define THREAD_GROUP_FLAGS_SHARED ( \
92 THREAD_GROUP_FLAGS_UI_APP | \
93 THREAD_GROUP_FLAGS_MANAGED | \
94 THREAD_GROUP_FLAGS_STRICT_TIMERS | \
95 THREAD_GROUP_FLAGS_GAME_MODE )
96
97static_assert(
98 (THREAD_GROUP_FLAGS_SHARED & THREAD_GROUP_EXCLUSIVE_FLAGS_MASK) == 0,
99 "valid shared flags");
100
101__BEGIN_DECLS
102
103void thread_group_init(void);
104void thread_group_resync(boolean_t create);
105struct thread_group *thread_group_create_and_retain(uint32_t flags);
106void thread_group_init_thread(thread_t t, task_t task);
107void thread_group_set_name(struct thread_group *tg, const char *name);
108void thread_group_flags_update_lock(void);
109void thread_group_flags_update_unlock(void);
110void thread_group_set_flags(struct thread_group *tg, uint32_t flags);
111uint32_t thread_group_get_flags(struct thread_group *);
112void thread_group_clear_flags(struct thread_group *tg, uint32_t flags);
113void thread_group_set_flags_locked(struct thread_group *tg, uint32_t flags);
114void thread_group_clear_flags_locked(struct thread_group *tg, uint32_t flags);
115boolean_t thread_group_valid_flags(uint32_t flags);
116struct thread_group *thread_group_find_by_name_and_retain(char *name);
117struct thread_group *thread_group_find_by_id_and_retain(uint64_t id);
118struct thread_group *thread_group_retain(struct thread_group *tg);
119void thread_group_release(struct thread_group *tg);
120void thread_group_release_live(struct thread_group *tg);
121void thread_group_deallocate_safe(struct thread_group *tg);
122struct thread_group *thread_group_get(thread_t t);
123struct thread_group *thread_group_get_home_group(thread_t t);
124void thread_group_set_bank(thread_t t, struct thread_group *tg);
125uint64_t thread_group_get_id(struct thread_group *tg);
126uint32_t thread_group_count(void);
127const char * thread_group_get_name(struct thread_group *tg);
128void * thread_group_get_machine_data(struct thread_group *tg);
129uint32_t thread_group_machine_data_size(void);
130boolean_t thread_group_uses_immediate_ipi(struct thread_group *tg);
131cluster_type_t thread_group_recommendation(struct thread_group *tg);
132
133typedef void (*thread_group_iterate_fn_t)(void*, int, struct thread_group *);
134kern_return_t thread_group_iterate_stackshot(thread_group_iterate_fn_t callout, void *arg);
135void thread_group_update_recommendation(struct thread_group *tg, cluster_type_t new_recommendation);
136uint64_t thread_group_id(struct thread_group *tg);
137
138void thread_set_work_interval_thread_group(thread_t t, struct thread_group *tg);
139#if CONFIG_SCHED_AUTO_JOIN
140void thread_set_autojoin_thread_group_locked(thread_t t, struct thread_group *tg);
141#endif
142#if CONFIG_PREADOPT_TG
143void thread_set_preadopt_thread_group(thread_t t, struct thread_group *tg);
144#endif
145
146void thread_resolve_and_enforce_thread_group_hierarchy_if_needed(thread_t t);
147
148#if XNU_KERNEL_PRIVATE
149void thread_group_vm_add(void);
150#endif
151
152__END_DECLS
153
154#endif /* CONFIG_THREAD_GROUPS */
155
156#endif // _KERN_THREAD_GROUP_H_
157