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 */
105
106/* Flags to be passed with work_interval_create() */
107
108/* If interval is joinable, create no longer implicitly joins, you must use work_interval_join */
109#define WORK_INTERVAL_FLAG_JOINABLE (0x1)
110/* Only threads that join the group are measured together, otherwise the group is the creator's home group */
111#define WORK_INTERVAL_FLAG_GROUP (0x2)
112
113/* Flags to describe the interval flavor to the performance controller */
114#define WORK_INTERVAL_TYPE_MASK (0xF0000000)
115#define WORK_INTERVAL_TYPE_DEFAULT (0x0 << 28)
116#define WORK_INTERVAL_TYPE_COREAUDIO (0x1 << 28)
117#define WORK_INTERVAL_TYPE_COREANIMATION (0x2 << 28)
118#define WORK_INTERVAL_TYPE_CA_RENDER_SERVER (0x2 << 28)
119#define WORK_INTERVAL_TYPE_CA_CLIENT (0x3 << 28)
120#define WORK_INTERVAL_TYPE_HID_DELIVERY (0x4 << 28)
121#define WORK_INTERVAL_TYPE_LAST (0xF << 28)
122
123#ifndef KERNEL
124
125typedef struct work_interval *work_interval_t;
126typedef struct work_interval_instance *work_interval_instance_t;
127
128/*
129 * Create a new work interval handle.
130 *
131 * May fail with EALREADY if the current group already has a work interval.
132 *
133 * With no flags:
134 * Auto-joins the work interval to the creating thread
135 * May only use interval_handle from creating thread
136 * Data provided affects native thread group
137 *
138 * With the JOINABLE flag
139 * interval_handle is usable by the process
140 * creating thread does not auto-join
141 * notifying thread must have joined when notifying
142 *
143 * With the GROUP flag
144 * creates a new thread group to isolate the joined threads from
145 * the rest of the process for performance controller analysis
146 * Threads which join the work interval become members of this new group
147 *
148 * TODO: Add a name parameter so that clients can name the work interval
149 * Can also take the thread name from the notifying thread
150 *
151 * Requires the 'com.apple.private.kernel.work-interval' entitlement (PRIV_WORK_INTERVAL)
152 *
153 * Note that joining a work interval supersedes automatic thread group management via vouchers
154 */
155int work_interval_create(work_interval_t *interval_handle, uint32_t flags);
156
157
158/*
159 * Notify the power management subsystem that the work for a current interval has completed
160 *
161 * Only the process which created the work interval may notify
162 */
163int work_interval_notify(work_interval_t interval_handle,
164 uint64_t start, uint64_t finish,
165 uint64_t deadline, uint64_t next_start,
166 uint32_t flags);
167
168/*
169 * Notify, with "finish" implicitly set to the current time
170 *
171 * Only the process which created the work interval may notify
172 */
173int work_interval_notify_simple(work_interval_t interval_handle,
174 uint64_t start, uint64_t deadline,
175 uint64_t next_start);
176
177/*
178 * Deallocate work interval handle
179 * For non-JOINABLE, also removes thread from work interval
180 * For JOINABLE, does not remove thread (needs a leave as well)
181 */
182int work_interval_destroy(work_interval_t interval_handle);
183
184/*
185 * Join work interval via work interval handle
186 * Only allowed if interval is using the joinable and group flags
187 *
188 * Supersedes automatic thread group management via vouchers
189 */
190int work_interval_join(work_interval_t interval_handle);
191
192/*
193 * extract Mach send right representing work interval thread group
194 * Returns a +1 send right ref, which must be deallocated via mach_port_deallocate
195 * Only allowed if interval is joinable, otherwise returns ENOTSUP
196 *
197 * Supersedes automatic thread group management via vouchers
198 */
199int work_interval_copy_port(work_interval_t interval_handle, mach_port_t *port);
200
201/*
202 * Join work interval via Mach send right
203 *
204 * Does NOT consume Mach send right, must deallocate with mach_port_deallocate after using
205 * It's safe to deallocate the right after joining, the thread will stay joined
206 *
207 * Can be sent to clients via xpc_dictionary_copy_mach_send, and similar
208 *
209 * Supersedes automatic thread group management via vouchers
210 *
211 * If the underlying work interval object is terminated then this may return ENOENT
212 * <rdar://problem/31819320>
213 */
214int work_interval_join_port(mach_port_t port);
215
216/*
217 * Leave the current thread's work interval
218 */
219int work_interval_leave(void);
220
221#endif /* !KERNEL */
222
223#if PRIVATE
224
225/* Private interface between Libsyscall and xnu */
226#define WORK_INTERVAL_OPERATION_CREATE 0x00000001 /* deprecated */
227#define WORK_INTERVAL_OPERATION_DESTROY 0x00000002 /* arg is NULL */
228#define WORK_INTERVAL_OPERATION_NOTIFY 0x00000003 /* arg is a work_interval_notification_t */
229#define WORK_INTERVAL_OPERATION_CREATE2 0x00000004 /* arg is a work_interval_create_params */
230#define WORK_INTERVAL_OPERATION_JOIN 0x00000005 /* arg is a port_name */
231
232struct work_interval_notification {
233 uint64_t start;
234 uint64_t finish;
235 uint64_t deadline;
236 uint64_t next_start;
237 uint32_t notify_flags;
238 uint32_t create_flags;
239};
240typedef struct work_interval_notification *work_interval_notification_t;
241
242struct work_interval_create_params {
243 uint64_t wicp_id; /* out param */
244 uint32_t wicp_port; /* out param */
245 uint32_t wicp_create_flags;
246};
247
248
249int __work_interval_ctl(uint32_t operation, uint64_t work_interval_id, void *arg, size_t len);
250
251#endif /* PRIVATE */
252
253__END_DECLS
254
255#endif /* _SYS_WORK_INTERVAL_H */
256
257