git.saurik.com Git - apple/xnu.git/blame_incremental

... / ...

Commit	Line	Data
	1	/*
	2	* Copyright (c) 2015 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/types.h>
	34	#include <sys/cdefs.h>
	35
	36	__BEGIN_DECLS
	37
	38	/*
	39	* Trusted clients with deadline-sensitive work may report information
	40	* about the execution of their work using the work interval facility.
	41	* This is intended to be a higher-level semantic than realtime scheduling,
	42	* which operates at the level of thread block/unblock. A high level
	43	* operation may have many blocking points, including IPC to other tasks,
	44	* and this this metric will capture the overall time to complete a unit of
	45	* work.
	46	*
	47	* A work interval is defined by several timestamps, namely (S)tart,
	48	* (F)inish, (D)eadline, and (N)ext start.
	49	*
	50	* ... ----+==================+--------+--+==== ...
	51	* \| \| \| \|
	52	* S F D N
	53	*
	54	* \__________________/
	55	* Active
	56	* \___________________________/
	57	* Work Interval
	58	*
	59	* \_________/
	60	* \|
	61	* report information here ---------+
	62	*
	63	* Definitions:
	64	*
	65	* Start: Absolute time when the current deadline-oriented work began. Due
	66	* to scheduling latency, preemption, and blocking points, the
	67	* thread controlling the work interval may actually begin
	68	* executing after this ideal time (which may be the previous work
	69	* interval's "next start")
	70	* Finish: Absolute time when the current deadline-oriented work finished.
	71	* This will typically be a timestamp taken before reporting using
	72	* the work interval interface.
	73	* Deadline: Absolute time by which the current work was expected to finish.
	74	* In cases where the amount of computation (or preemption, or time
	75	* spent blocked) causes the active period to take longer than
	76	* expected, F may be greater than D.
	77	* Next start: Absolute time when the next deadline-oriented work is
	78	* expected to begin. This is typically the same as Deadline.
	79	* Active: The fraction of the work interval spent completing the work. In
	80	* cases where the Finish time exceeded the Deadline, this fraction
	81	* will be >1.0.
	82	*
	83	* Basic Use:
	84	*
	85	* Clients should report information for a work interval after finishing
	86	* work for the current interval but before the next work interval begins.
	87	*
	88	* If Finish far exceeds the previously expected Deadline, the
	89	* caller may adjust Next Start to align to a multiple of the period
	90	* (and skip over several work intervals that could not be
	91	* executed).
	92	*
	93	* Caution (!):
	94	*
	95	* Because the information supplied via this facility directly influences power
	96	* management decisions, clients should strive to be as accurate as possible.
	97	* Failure to do so will adversely impact system power and performance.
	98	*
	99	*/
	100	#ifndef KERNEL
	101
	102	typedef struct work_interval *work_interval_t;
	103
	104	/* Create a new work interval handle (currently for the current thread only). Flags is unused */
	105	int work_interval_create(work_interval_t *interval_handle, uint32_t flags);
	106
	107	/* Notify the power management subsystem that the work for a current interval has completed */
	108	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);
	109
	110	/* Notify, with "finish" implicitly set to the current time */
	111	int work_interval_notify_simple(work_interval_t interval_handle, uint64_t start, uint64_t deadline, uint64_t next_start);
	112
	113	/* Deallocate work interval (currently for the current thread only) */
	114	int work_interval_destroy(work_interval_t interval_handle);
	115
	116	#endif /* KERNEL */
	117
	118	#if PRIVATE
	119
	120	/* Private interface between Libsyscall and xnu */
	121	#define WORK_INTERVAL_OPERATION_CREATE 0x00000001 /* arg is a uint64_t * that accepts work interval ID as an OUT param */
	122	#define WORK_INTERVAL_OPERATION_DESTROY 0x00000002
	123	#define WORK_INTERVAL_OPERATION_NOTIFY 0x00000003 /* arg is a work_interval_notification_t */
	124
	125	struct work_interval_notification {
	126	uint64_t start;
	127	uint64_t finish;
	128	uint64_t deadline;
	129	uint64_t next_start;
	130	uint32_t flags;
	131	uint32_t unused1;
	132	};
	133	typedef struct work_interval_notification *work_interval_notification_t;
	134
	135	int __work_interval_ctl(uint32_t operation, uint64_t work_interval_id, void *arg, size_t len);
	136
	137	#endif /* PRIVATE */
	138
	139	__END_DECLS
	140
	141	#endif /* _SYS_WORK_INTERVAL_H */