1/*
2 * Copyright (c) 2015-2017 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#ifndef _SYS_WORK_INTERVAL_H
30#define _SYS_WORK_INTERVAL_H
31
32#include <stdint.h>
33#include <sys/cdefs.h>
34#include <sys/_types/_size_t.h>
35
36#include <mach/port.h>
37
38__BEGIN_DECLS
39
40/*
41 * A work interval is a repeatable unit of work characterized by a
42 * start, finish, and deadline.
43 *
44 * Trusted clients with deadline-sensitive work may report information
45 * about the execution of their work using the work interval facility.
46 * This is intended to be a higher-level semantic than realtime scheduling,
47 * which operates at the level of thread block/unblock. A high level
48 * operation may have many blocking points, including IPC to other tasks,
49 * and this this metric will capture the overall time to complete a unit of
50 * work.
51 *
52 * A work interval is defined by several timestamps, namely (S)tart,
53 * (F)inish, (D)eadline, and (N)ext start.
54 *
55 * ... ----+==================+--------+--+==== ...
56 * | | | |
57 * S F D N
58 *
59 * \__________________/
60 * Active
61 * \___________________________/
62 * Work Interval
63 *
64 * \_________/
65 * |
66 * report information here ---------+
67 *
68 * Definitions:
69 *
70 * Start: Absolute time when the current deadline-oriented work began. Due
71 * to scheduling latency, preemption, and blocking points, the
72 * thread controlling the work interval may actually begin
73 * executing after this ideal time (which may be the previous work
74 * interval's "next start")
75 * Finish: Absolute time when the current deadline-oriented work finished.
76 * This will typically be a timestamp taken before reporting using
77 * the work interval interface.
78 * Deadline: Absolute time by which the current work was expected to finish.
79 * In cases where the amount of computation (or preemption, or time
80 * spent blocked) causes the active period to take longer than
81 * expected, F may be greater than D.
82 * Next start: Absolute time when the next deadline-oriented work is
83 * expected to begin. This is typically the same as Deadline.
84 * Active: The fraction of the work interval spent completing the work. In
85 * cases where the Finish time exceeded the Deadline, this fraction
86 * will be >1.0.
87 *
88 * Basic Use:
89 *
90 * Clients should report information for a work interval after finishing
91 * work for the current interval but before the next work interval begins.
92 *
93 * If Finish far exceeds the previously expected Deadline, the
94 * caller may adjust Next Start to align to a multiple of the period
95 * (and skip over several work intervals that could not be
96 * executed).
97 *
98 * Caution (!):
99 *
100 * Because the information supplied via this facility directly influences power
101 * management decisions, clients should strive to be as accurate as possible.
102 * Failure to do so will adversely impact system power and performance.
103 *
104 * Work Interval Auto Join Support:
105 *
106 * Work intervals support an optional flag WORK_INTERVAL_FLAG_ENABLE_AUTO_JOIN
107 * which allows RT threads from the same home thread group to join work
108 * intervals via wakeup relationship tracking. Based on the join policy,
109 * RT threads can temporarily join the work interval of other RT threads
110 * which make them runnable. The auto joined thread remains in the work
111 * interval until it blocks or terminates. The mechanism works through
112 * make runnable heuristic and it should be used with extreme caution.
113 * If a client specifies this flag, it gives up explicit control over its
114 * thread group membership and threads unrelated to the work interval
115 * could become part of the thread group. This could lead to serious power
116 * and performance issues. If the make runnable heuristic does not work
117 * for a client use case, it should adopt work_interval_join_port() or
118 * work_interval_join() to explicitly declare its intent.
119 *
120 * Work Interval Deferred Finish Support:
121 *
122 * Another advanced feature for work intervals is the ability to defer the finish
123 * calls for the work interval until all auto-joined threads for the work interval
124 * have blocked or terminated. This feature is enabled via an optional flag
125 * WORK_INTERVAL_FLAG_ENABLE_DEFERRED_FINISH and is valid only if the work interval
126 * is configured with the WORK_INTERVAL_FLAG_ENABLE_AUTO_JOIN flag as well. The
127 * deferred finish mechanism allows the work interval to defer the finish call
128 * for the work interval until all auto-join threads have blocked/terminated
129 * (and have therefore un-joined the work interval) or one of the work interval
130 * threads calls start for the next frame. The deferred finish works only for
131 * workloads that have no temporal overlap across frames i.e. previous frame has to
132 * finish before next frame can start. This feature should be used with caution
133 * since auto-joined threads would delay finish calls to the performance controller
134 * which could lead to poor performance and battery life.
135 */
136
137/* Flags to be passed with work_interval_create() */
138
139/* If interval is joinable, create no longer implicitly joins, you must use work_interval_join */
140#define WORK_INTERVAL_FLAG_JOINABLE (0x1)
141/* Only threads that join the group are measured together, otherwise the group is the creator's home group */
142#define WORK_INTERVAL_FLAG_GROUP (0x2)
143/* Specifies that the work interval is being created by a client who doesn't
144 * necessarily have the PRIV_WORK_INTERVAL entitlement. Skip privilege checks.
145 * This can only be masked in for work intervals of types COREAUDIO, CA_CLIENT
146 * and DEFAULT */
147#define WORK_INTERVAL_FLAG_UNRESTRICTED (0x4)
148
149/* [Advanced Flag] Read section on "Work Interval Auto Join Support" above for details */
150#define WORK_INTERVAL_FLAG_ENABLE_AUTO_JOIN (0x8)
151/* [Advanced Flag] Read section on "Work Interval Deferred Finish Support" above for details */
152#define WORK_INTERVAL_FLAG_ENABLE_DEFERRED_FINISH (0x10)
153
154/* Kernel-supplied flag: Work interval has been ignored by the kernel */
155#define WORK_INTERVAL_FLAG_IGNORED (0x20)
156
157/* Specifies that the work interval requests the system to provide just enough performance
158 * to be able to finish at the provided deadline and no sooner. */
159#define WORK_INTERVAL_FLAG_FINISH_AT_DEADLINE (0x40)
160
161/* Internal-only flag: workinterval will have the SET_WORKLOAD_ID operation called on it immediately
162 * after creation. */
163#define WORK_INTERVAL_FLAG_HAS_WORKLOAD_ID (0x80)
164
165/* Internal-only flag: Telemetry data will be aggregated from threads while they are joined to
166 * the work interval. */
167#define WORK_INTERVAL_FLAG_ENABLE_TELEMETRY_DATA (0x100)
168
169/* Flags to describe the interval flavor to the performance controller */
170#define WORK_INTERVAL_TYPE_MASK (0xF0000000)
171#define WORK_INTERVAL_TYPE_DEFAULT (0x0 << 28)
172#define WORK_INTERVAL_TYPE_COREAUDIO (0x1 << 28)
173#define WORK_INTERVAL_TYPE_COREANIMATION (0x2 << 28)
174#define WORK_INTERVAL_TYPE_CA_RENDER_SERVER (0x2 << 28)
175#define WORK_INTERVAL_TYPE_CA_CLIENT (0x3 << 28)
176#define WORK_INTERVAL_TYPE_HID_DELIVERY (0x4 << 28)
177#define WORK_INTERVAL_TYPE_COREMEDIA (0x5 << 28)
178#define WORK_INTERVAL_TYPE_ARKIT (0x6 << 28)
179#define WORK_INTERVAL_TYPE_FRAME_COMPOSITOR (0x7 << 28)
180#define WORK_INTERVAL_TYPE_LAST (0xF << 28)
181
182#ifndef KERNEL
183
184typedef struct work_interval *work_interval_t;
185typedef struct work_interval_instance *work_interval_instance_t;
186typedef struct work_interval_data *work_interval_data_t;
187
188/*
189 * Create a new work interval handle.
190 *
191 * May fail with EALREADY if the current group already has a work interval.
192 *
193 * With no flags:
194 * Auto-joins the work interval to the creating thread
195 * May only use interval_handle from creating thread
196 * Data provided affects native thread group
197 *
198 * With the JOINABLE flag
199 * interval_handle is usable by the process
200 * creating thread does not auto-join
201 * notifying thread must have joined when notifying
202 *
203 * With the GROUP flag
204 * creates a new thread group to isolate the joined threads from
205 * the rest of the process for performance controller analysis
206 * Threads which join the work interval become members of this new group
207 *
208 * TODO: Add a name parameter so that clients can name the work interval
209 * Can also take the thread name from the notifying thread
210 *
211 * Requires the 'com.apple.private.kernel.work-interval' entitlement (PRIV_WORK_INTERVAL)
212 *
213 * Note that joining a work interval supersedes automatic thread group management via vouchers
214 */
215int work_interval_create(work_interval_t *interval_handle, uint32_t flags);
216
217/* Returns the flags used for the work interval when it was created.
218 *
219 * May fail with EINVAL if the port isn't from a prior call to
220 * work_interval_copy_port.
221 */
222int work_interval_get_flags_from_port(mach_port_t port, uint32_t *flags);
223
224
225/*
226 * Notify the power management subsystem that the work for a current interval has completed
227 *
228 * Only the process which created the work interval may notify
229 */
230int work_interval_notify(work_interval_t interval_handle,
231 uint64_t start, uint64_t finish,
232 uint64_t deadline, uint64_t next_start,
233 uint32_t flags);
234
235/*
236 * Notify, with "finish" implicitly set to the current time
237 *
238 * Only the process which created the work interval may notify
239 */
240int work_interval_notify_simple(work_interval_t interval_handle,
241 uint64_t start, uint64_t deadline,
242 uint64_t next_start);
243
244/*
245 * Deallocate work interval handle
246 * For non-JOINABLE, also removes thread from work interval
247 * For JOINABLE, does not remove thread (needs a leave as well)
248 */
249int work_interval_destroy(work_interval_t interval_handle);
250
251/*
252 * Join work interval via work interval handle
253 * Only allowed if interval is using the joinable and group flags
254 *
255 * Supersedes automatic thread group management via vouchers
256 */
257int work_interval_join(work_interval_t interval_handle);
258
259/*
260 * extract Mach send right representing work interval thread group
261 * Returns a +1 send right ref, which must be deallocated via mach_port_deallocate
262 * Only allowed if interval is joinable, otherwise returns ENOTSUP
263 *
264 * Supersedes automatic thread group management via vouchers
265 */
266int work_interval_copy_port(work_interval_t interval_handle, mach_port_t *port);
267
268/*
269 * Join work interval via Mach send right
270 *
271 * Does NOT consume Mach send right, must deallocate with mach_port_deallocate after using
272 * It's safe to deallocate the right after joining, the thread will stay joined
273 *
274 * Can be sent to clients via xpc_dictionary_copy_mach_send, and similar
275 *
276 * Supersedes automatic thread group management via vouchers
277 *
278 * If the underlying work interval object is terminated then this may return ENOENT
279 * <rdar://problem/31819320>
280 */
281int work_interval_join_port(mach_port_t port);
282
283/*
284 * Leave the current thread's work interval
285 */
286int work_interval_leave(void);
287
288#endif /* !KERNEL */
289
290
291#if PRIVATE
292
293/* Private interface between Libsyscall and xnu */
294#define WORK_INTERVAL_OPERATION_CREATE 0x00000001 /* deprecated */
295#define WORK_INTERVAL_OPERATION_DESTROY 0x00000002 /* arg is NULL */
296#define WORK_INTERVAL_OPERATION_NOTIFY 0x00000003 /* arg is a work_interval_notification_t */
297#define WORK_INTERVAL_OPERATION_CREATE2 0x00000004 /* arg is a work_interval_create_params */
298#define WORK_INTERVAL_OPERATION_JOIN 0x00000005 /* arg is a port_name */
299#define WORK_INTERVAL_OPERATION_GET_FLAGS 0x00000009 /* arg is a port name */
300#define WORK_INTERVAL_OPERATION_SET_NAME 0x0000000a /* arg is name string (char[WORK_INTERVAL_NAME_MAX])*/
301#define WORK_INTERVAL_OPERATION_SET_WORKLOAD_ID 0x0000000b /* arg is a work_interval_workload_id_params */
302#define WORK_INTERVAL_NAME_MAX 32
303#define WORK_INTERVAL_WORKLOAD_ID_NAME_MAX 64
304
305/* Flags passed in work_interval_workload_id_params wlidp_flags field */
306#define WORK_INTERVAL_WORKLOAD_ID_HAS_ID (1u << 0)
307#define WORK_INTERVAL_WORKLOAD_ID_RT_ALLOWED (1u << 1)
308#define WORK_INTERVAL_WORKLOAD_ID_RT_CRITICAL (1u << 2)
309
310/* Flags allowed to be passed in from userspace as part of kern_work_interval_set_workload_id() */
311#define WORK_INTERVAL_SET_WORKLOAD_ID_FLAGS_MASK (WORK_INTERVAL_WORKLOAD_ID_RT_CRITICAL | WORK_INTERVAL_WORKLOAD_ID_RT_ALLOWED)
312
313#ifdef XNU_KERNEL_PRIVATE
314
315/* Marker that workinterval was joined before workload ID was set */
316#define WORK_INTERVAL_WORKLOAD_ID_ALREADY_JOINED (1u << 31)
317/* Work interval is allowed to provide complexity values per frame as part of {start, update, finish} calls */
318#define WORK_INTERVAL_WORKLOAD_ID_COMPLEXITY_ALLOWED (1u << 30)
319
320#endif /* XNU_KERNEL_PRIVATE */
321
322struct work_interval_notification {
323 uint64_t start;
324 uint64_t finish;
325 uint64_t deadline;
326 uint64_t next_start;
327 uint32_t notify_flags;
328 uint32_t create_flags;
329};
330typedef struct work_interval_notification *work_interval_notification_t;
331
332struct work_interval_create_params {
333 uint64_t wicp_id; /* in/out param */
334 mach_port_name_t wicp_port; /* in/out param */
335 uint32_t wicp_create_flags;
336};
337
338struct work_interval_workload_id_params {
339 uint32_t wlidp_flags; /* in/out param */
340 uint32_t wlidp_wicreate_flags; /* in/out param */
341 uint64_t wlidp_name; /* in param (pointer to char[WORK_INTERVAL_WORKLOAD_ID_NAME_MAX])*/
342 uint64_t wlidp_syscall_mask[2]; /* out param (needs to fit MACH_TRAP_TABLE_COUNT + nsysent bits) */
343};
344
345
346int __work_interval_ctl(uint32_t operation, uint64_t work_interval_id, void *arg, size_t len);
347
348#endif /* PRIVATE */
349
350__END_DECLS
351
352#endif /* _SYS_WORK_INTERVAL_H */
353