mirror of
https://github.com/darlinghq/darling-xnu.git
synced 2024-11-23 04:29:53 +00:00
314 lines
13 KiB
C
314 lines
13 KiB
C
/*
|
|
* Copyright (c) 2015-2017 Apple Inc. All rights reserved.
|
|
*
|
|
* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
|
|
*
|
|
* This file contains Original Code and/or Modifications of Original Code
|
|
* as defined in and that are subject to the Apple Public Source License
|
|
* Version 2.0 (the 'License'). You may not use this file except in
|
|
* compliance with the License. The rights granted to you under the License
|
|
* may not be used to create, or enable the creation or redistribution of,
|
|
* unlawful or unlicensed copies of an Apple operating system, or to
|
|
* circumvent, violate, or enable the circumvention or violation of, any
|
|
* terms of an Apple operating system software license agreement.
|
|
*
|
|
* Please obtain a copy of the License at
|
|
* http://www.opensource.apple.com/apsl/ and read it before using this file.
|
|
*
|
|
* The Original Code and all software distributed under the License are
|
|
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
|
|
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
|
|
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
|
|
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
|
|
* Please see the License for the specific language governing rights and
|
|
* limitations under the License.
|
|
*
|
|
* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
|
|
*/
|
|
|
|
#ifndef _SYS_WORK_INTERVAL_H
|
|
#define _SYS_WORK_INTERVAL_H
|
|
|
|
#include <stdint.h>
|
|
#include <sys/cdefs.h>
|
|
#include <sys/_types/_size_t.h>
|
|
|
|
#include <mach/port.h>
|
|
|
|
__BEGIN_DECLS
|
|
|
|
/*
|
|
* A work interval is a repeatable unit of work characterized by a
|
|
* start, finish, and deadline.
|
|
*
|
|
* Trusted clients with deadline-sensitive work may report information
|
|
* about the execution of their work using the work interval facility.
|
|
* This is intended to be a higher-level semantic than realtime scheduling,
|
|
* which operates at the level of thread block/unblock. A high level
|
|
* operation may have many blocking points, including IPC to other tasks,
|
|
* and this this metric will capture the overall time to complete a unit of
|
|
* work.
|
|
*
|
|
* A work interval is defined by several timestamps, namely (S)tart,
|
|
* (F)inish, (D)eadline, and (N)ext start.
|
|
*
|
|
* ... ----+==================+--------+--+==== ...
|
|
* | | | |
|
|
* S F D N
|
|
*
|
|
* \__________________/
|
|
* Active
|
|
* \___________________________/
|
|
* Work Interval
|
|
*
|
|
* \_________/
|
|
* |
|
|
* report information here ---------+
|
|
*
|
|
* Definitions:
|
|
*
|
|
* Start: Absolute time when the current deadline-oriented work began. Due
|
|
* to scheduling latency, preemption, and blocking points, the
|
|
* thread controlling the work interval may actually begin
|
|
* executing after this ideal time (which may be the previous work
|
|
* interval's "next start")
|
|
* Finish: Absolute time when the current deadline-oriented work finished.
|
|
* This will typically be a timestamp taken before reporting using
|
|
* the work interval interface.
|
|
* Deadline: Absolute time by which the current work was expected to finish.
|
|
* In cases where the amount of computation (or preemption, or time
|
|
* spent blocked) causes the active period to take longer than
|
|
* expected, F may be greater than D.
|
|
* Next start: Absolute time when the next deadline-oriented work is
|
|
* expected to begin. This is typically the same as Deadline.
|
|
* Active: The fraction of the work interval spent completing the work. In
|
|
* cases where the Finish time exceeded the Deadline, this fraction
|
|
* will be >1.0.
|
|
*
|
|
* Basic Use:
|
|
*
|
|
* Clients should report information for a work interval after finishing
|
|
* work for the current interval but before the next work interval begins.
|
|
*
|
|
* If Finish far exceeds the previously expected Deadline, the
|
|
* caller may adjust Next Start to align to a multiple of the period
|
|
* (and skip over several work intervals that could not be
|
|
* executed).
|
|
*
|
|
* Caution (!):
|
|
*
|
|
* Because the information supplied via this facility directly influences power
|
|
* management decisions, clients should strive to be as accurate as possible.
|
|
* Failure to do so will adversely impact system power and performance.
|
|
*
|
|
* Work Interval Auto Join Support:
|
|
*
|
|
* Work intervals support an optional flag WORK_INTERVAL_FLAG_ENABLE_AUTO_JOIN
|
|
* which allows RT threads from the same home thread group to join work
|
|
* intervals via wakeup relationship tracking. Based on the join policy,
|
|
* RT threads can temporarily join the work interval of other RT threads
|
|
* which make them runnable. The auto joined thread remains in the work
|
|
* interval until it blocks or terminates. The mechanism works through
|
|
* make runnable heuristic and it should be used with extreme caution.
|
|
* If a client specifies this flag, it gives up explicit control over its
|
|
* thread group membership and threads unrelated to the work interval
|
|
* could become part of the thread group. This could lead to serious power
|
|
* and performance issues. If the make runnable heuristic does not work
|
|
* for a client use case, it should adopt work_interval_join_port() or
|
|
* work_interval_join() to explicitly declare its intent.
|
|
*
|
|
* Work Interval Deferred Finish Support:
|
|
*
|
|
* Another advanced feature for work intervals is the ability to defer the finish
|
|
* calls for the work interval until all auto-joined threads for the work interval
|
|
* have blocked or terminated. This feature is enabled via an optional flag
|
|
* WORK_INTERVAL_FLAG_ENABLE_DEFERRED_FINISH and is valid only if the work interval
|
|
* is configured with the WORK_INTERVAL_FLAG_ENABLE_AUTO_JOIN flag as well. The
|
|
* deferred finish mechanism allows the work interval to defer the finish call
|
|
* for the work interval until all auto-join threads have blocked/terminated
|
|
* (and have therefore un-joined the work interval) or one of the work interval
|
|
* threads calls start for the next frame. The deferred finish works only for
|
|
* workloads that have no temporal overlap across frames i.e. previous frame has to
|
|
* finish before next frame can start. This feature should be used with caution
|
|
* since auto-joined threads would delay finish calls to the performance controller
|
|
* which could lead to poor performance and battery life.
|
|
*/
|
|
|
|
/* Flags to be passed with work_interval_create() */
|
|
|
|
/* If interval is joinable, create no longer implicitly joins, you must use work_interval_join */
|
|
#define WORK_INTERVAL_FLAG_JOINABLE (0x1)
|
|
/* Only threads that join the group are measured together, otherwise the group is the creator's home group */
|
|
#define WORK_INTERVAL_FLAG_GROUP (0x2)
|
|
/* Specifies that the work interval is being created by a client who doesn't
|
|
* necessarily have the PRIV_WORK_INTERVAL entitlement. Skip privilege checks.
|
|
* This can only be masked in for work intervals of types COREAUDIO, CA_CLIENT
|
|
* and DEFAULT */
|
|
#define WORK_INTERVAL_FLAG_UNRESTRICTED (0x4)
|
|
|
|
/* [Advanced Flag] Read section on "Work Interval Auto Join Support" above for details */
|
|
#define WORK_INTERVAL_FLAG_ENABLE_AUTO_JOIN (0x8)
|
|
/* [Advanced Flag] Read section on "Work Interval Deferred Finish Support" above for details */
|
|
#define WORK_INTERVAL_FLAG_ENABLE_DEFERRED_FINISH (0x10)
|
|
|
|
/* Kernel-supplied flag: Work interval has been ignored by the kernel */
|
|
#define WORK_INTERVAL_FLAG_IGNORED (0x20)
|
|
|
|
/* Specifies that the work interval requests the system to provide just enough performance
|
|
* to be able to finish at the provided deadline and no sooner. */
|
|
#define WORK_INTERVAL_FLAG_FINISH_AT_DEADLINE (0x40)
|
|
|
|
/* Flags to describe the interval flavor to the performance controller */
|
|
#define WORK_INTERVAL_TYPE_MASK (0xF0000000)
|
|
#define WORK_INTERVAL_TYPE_DEFAULT (0x0 << 28)
|
|
#define WORK_INTERVAL_TYPE_COREAUDIO (0x1 << 28)
|
|
#define WORK_INTERVAL_TYPE_COREANIMATION (0x2 << 28)
|
|
#define WORK_INTERVAL_TYPE_CA_RENDER_SERVER (0x2 << 28)
|
|
#define WORK_INTERVAL_TYPE_CA_CLIENT (0x3 << 28)
|
|
#define WORK_INTERVAL_TYPE_HID_DELIVERY (0x4 << 28)
|
|
#define WORK_INTERVAL_TYPE_COREMEDIA (0x5 << 28)
|
|
#define WORK_INTERVAL_TYPE_ARKIT (0x6 << 28)
|
|
#define WORK_INTERVAL_TYPE_LAST (0xF << 28)
|
|
|
|
#ifndef KERNEL
|
|
|
|
typedef struct work_interval *work_interval_t;
|
|
typedef struct work_interval_instance *work_interval_instance_t;
|
|
|
|
/*
|
|
* Create a new work interval handle.
|
|
*
|
|
* May fail with EALREADY if the current group already has a work interval.
|
|
*
|
|
* With no flags:
|
|
* Auto-joins the work interval to the creating thread
|
|
* May only use interval_handle from creating thread
|
|
* Data provided affects native thread group
|
|
*
|
|
* With the JOINABLE flag
|
|
* interval_handle is usable by the process
|
|
* creating thread does not auto-join
|
|
* notifying thread must have joined when notifying
|
|
*
|
|
* With the GROUP flag
|
|
* creates a new thread group to isolate the joined threads from
|
|
* the rest of the process for performance controller analysis
|
|
* Threads which join the work interval become members of this new group
|
|
*
|
|
* TODO: Add a name parameter so that clients can name the work interval
|
|
* Can also take the thread name from the notifying thread
|
|
*
|
|
* Requires the 'com.apple.private.kernel.work-interval' entitlement (PRIV_WORK_INTERVAL)
|
|
*
|
|
* Note that joining a work interval supersedes automatic thread group management via vouchers
|
|
*/
|
|
int work_interval_create(work_interval_t *interval_handle, uint32_t flags);
|
|
|
|
/* Returns the flags used for the work interval when it was created.
|
|
*
|
|
* May fail with EINVAL if the port isn't from a prior call to
|
|
* work_interval_copy_port.
|
|
*/
|
|
int work_interval_get_flags_from_port(mach_port_t port, uint32_t *flags);
|
|
|
|
|
|
/*
|
|
* Notify the power management subsystem that the work for a current interval has completed
|
|
*
|
|
* Only the process which created the work interval may notify
|
|
*/
|
|
int work_interval_notify(work_interval_t interval_handle,
|
|
uint64_t start, uint64_t finish,
|
|
uint64_t deadline, uint64_t next_start,
|
|
uint32_t flags);
|
|
|
|
/*
|
|
* Notify, with "finish" implicitly set to the current time
|
|
*
|
|
* Only the process which created the work interval may notify
|
|
*/
|
|
int work_interval_notify_simple(work_interval_t interval_handle,
|
|
uint64_t start, uint64_t deadline,
|
|
uint64_t next_start);
|
|
|
|
/*
|
|
* Deallocate work interval handle
|
|
* For non-JOINABLE, also removes thread from work interval
|
|
* For JOINABLE, does not remove thread (needs a leave as well)
|
|
*/
|
|
int work_interval_destroy(work_interval_t interval_handle);
|
|
|
|
/*
|
|
* Join work interval via work interval handle
|
|
* Only allowed if interval is using the joinable and group flags
|
|
*
|
|
* Supersedes automatic thread group management via vouchers
|
|
*/
|
|
int work_interval_join(work_interval_t interval_handle);
|
|
|
|
/*
|
|
* extract Mach send right representing work interval thread group
|
|
* Returns a +1 send right ref, which must be deallocated via mach_port_deallocate
|
|
* Only allowed if interval is joinable, otherwise returns ENOTSUP
|
|
*
|
|
* Supersedes automatic thread group management via vouchers
|
|
*/
|
|
int work_interval_copy_port(work_interval_t interval_handle, mach_port_t *port);
|
|
|
|
/*
|
|
* Join work interval via Mach send right
|
|
*
|
|
* Does NOT consume Mach send right, must deallocate with mach_port_deallocate after using
|
|
* It's safe to deallocate the right after joining, the thread will stay joined
|
|
*
|
|
* Can be sent to clients via xpc_dictionary_copy_mach_send, and similar
|
|
*
|
|
* Supersedes automatic thread group management via vouchers
|
|
*
|
|
* If the underlying work interval object is terminated then this may return ENOENT
|
|
* <rdar://problem/31819320>
|
|
*/
|
|
int work_interval_join_port(mach_port_t port);
|
|
|
|
/*
|
|
* Leave the current thread's work interval
|
|
*/
|
|
int work_interval_leave(void);
|
|
|
|
#endif /* !KERNEL */
|
|
|
|
#if PRIVATE
|
|
|
|
/* Private interface between Libsyscall and xnu */
|
|
#define WORK_INTERVAL_OPERATION_CREATE 0x00000001 /* deprecated */
|
|
#define WORK_INTERVAL_OPERATION_DESTROY 0x00000002 /* arg is NULL */
|
|
#define WORK_INTERVAL_OPERATION_NOTIFY 0x00000003 /* arg is a work_interval_notification_t */
|
|
#define WORK_INTERVAL_OPERATION_CREATE2 0x00000004 /* arg is a work_interval_create_params */
|
|
#define WORK_INTERVAL_OPERATION_JOIN 0x00000005 /* arg is a port_name */
|
|
#define WORK_INTERVAL_OPERATION_GET_FLAGS 0x00000009 /* arg is a port name */
|
|
|
|
struct work_interval_notification {
|
|
uint64_t start;
|
|
uint64_t finish;
|
|
uint64_t deadline;
|
|
uint64_t next_start;
|
|
uint32_t notify_flags;
|
|
uint32_t create_flags;
|
|
};
|
|
typedef struct work_interval_notification *work_interval_notification_t;
|
|
|
|
struct work_interval_create_params {
|
|
uint64_t wicp_id; /* in/out param */
|
|
mach_port_name_t wicp_port; /* in/out param */
|
|
uint32_t wicp_create_flags;
|
|
};
|
|
|
|
|
|
int __work_interval_ctl(uint32_t operation, uint64_t work_interval_id, void *arg, size_t len);
|
|
|
|
#endif /* PRIVATE */
|
|
|
|
__END_DECLS
|
|
|
|
#endif /* _SYS_WORK_INTERVAL_H */
|