[apple/xnu.git] / osfmk / kern / energy_perf.h

/*
 * Copyright (c) 2013 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@
 */

/*
 * Interfaces for non-kernel managed devices to inform the kernel of their
 * energy and performance relevant activity and resource utilisation, typically
 * on a per-thread or task basis.
 */

#ifndef _KERN_ENERGY_PERF_H_
#define _KERN_ENERGY_PERF_H_

#include <stdint.h>

#ifdef KERNEL
__BEGIN_DECLS

typedef struct {
	uint32_t gpu_id;
	uint32_t gpu_max_domains;
} gpu_descriptor;

typedef gpu_descriptor *gpu_descriptor_t;
/* The GPU is expected to describe itself with this interface prior to reporting
 * resource usage.
 */
void gpu_describe(gpu_descriptor_t);

#define GPU_SCOPE_CURRENT_THREAD (0x1)
#define GPU_SCOPE_MISC (0x2)

/* GPU utilisation update for the current thread. */
uint64_t gpu_accumulate_time(uint32_t scope, uint32_t gpu_id, uint32_t gpu_domain, uint64_t gpu_accumulated_ns, uint64_t gpu_tstamp_ns);

/* Interfaces for the block storage driver to advise the perf. controller of
 * recent IOs
 */

/* Target medium for this set of IOs. Updates can occur in parallel if
 * multiple devices exist, hence consumers must synchronize internally, ideally
 * in a low-overhead fashion such as per-CPU counters, as this may be invoked
 * within the IO path.
 */

#define IO_MEDIUM_ROTATING (0x0ULL)
#define IO_MEDIUM_SOLID_STATE (0x1ULL)

/* As there are several priority bands whose nature is evolving, we rely on the
 * block storage driver to classify non-performance-critical IOs as "low"
 * priority. Separate updates are expected for low/high priority IOs.
 */

#define IO_PRIORITY_LOW (0x1ULL << 8)

/* Reserved for estimates of bursts of future IOs; could possibly benefit from
 * a time horizon, but it's unclear if it will be specifiable by any layer with
 * reasonable accuracy
 */
#define IO_PRIORITY_PREDICTIVE (0x1ULL << 16)

uint64_t io_rate_update(
	uint64_t io_rate_flags, /* Rotating/NAND, IO priority level */
	uint64_t read_ops_delta,
	uint64_t write_ops_delta,
	uint64_t read_bytes_delta,
	uint64_t write_bytes_delta);

typedef uint64_t (*io_rate_update_callback_t) (uint64_t, uint64_t, uint64_t, uint64_t, uint64_t);

void io_rate_update_register(io_rate_update_callback_t);

/* Interfaces for integrated GPUs to supply command submission telemetry.
 */

#define GPU_NCMDS_VALID (0x1)
#define GPU_NOUTSTANDING_VALID (0x2)
#define GPU_BUSY_VALID (0x4)
#define GPU_CYCLE_COUNT_VALID (0x8)
#define GPU_MISC_VALID (0x10)

void gpu_submission_telemetry(
	uint64_t gpu_ncmds_total,
	uint64_t gpu_noutstanding,
	uint64_t gpu_busy_ns_total,
	uint64_t gpu_cycles,
	uint64_t gpu_telemetry_valid_flags,
	uint64_t gpu_telemetry_misc);

typedef uint64_t (*gpu_set_fceiling_t) (uint32_t gpu_fceiling_ratio, uint64_t gpu_fceiling_param);

void gpu_fceiling_cb_register(gpu_set_fceiling_t);

__END_DECLS
#endif /* KERNEL */

#endif /* _KERN_ENERGY_PERF_H_ */
Commit	Line	Data
fe8ab488 A	1	/*
	2	* Copyright (c) 2013 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	* Interfaces for non-kernel managed devices to inform the kernel of their
	31	* energy and performance relevant activity and resource utilisation, typically
	32	* on a per-thread or task basis.
	33	*/
	34
	35	#ifndef _KERN_ENERGY_PERF_H_
	36	#define _KERN_ENERGY_PERF_H_
	37
	38	#include <stdint.h>
	39
	40	#ifdef KERNEL
	41	__BEGIN_DECLS
	42
	43	typedef struct {
	44	uint32_t gpu_id;
	45	uint32_t gpu_max_domains;
	46	} gpu_descriptor;
	47
	48	typedef gpu_descriptor *gpu_descriptor_t;
	49	/* The GPU is expected to describe itself with this interface prior to reporting
	50	* resource usage.
	51	*/
	52	void gpu_describe(gpu_descriptor_t);
	53
	54	#define GPU_SCOPE_CURRENT_THREAD (0x1)
	55	#define GPU_SCOPE_MISC (0x2)
	56
	57	/* GPU utilisation update for the current thread. */
	58	uint64_t gpu_accumulate_time(uint32_t scope, uint32_t gpu_id, uint32_t gpu_domain, uint64_t gpu_accumulated_ns, uint64_t gpu_tstamp_ns);
	59
	60	/* Interfaces for the block storage driver to advise the perf. controller of
	61	* recent IOs
	62	*/
	63
	64	/* Target medium for this set of IOs. Updates can occur in parallel if
65	* multiple devices exist, hence consumers must synchronize internally, ideally
66	* in a low-overhead fashion such as per-CPU counters, as this may be invoked
67	* within the IO path.
68	*/
69
70	#define IO_MEDIUM_ROTATING (0x0ULL)
71	#define IO_MEDIUM_SOLID_STATE (0x1ULL)
72
73	/* As there are several priority bands whose nature is evolving, we rely on the
74	* block storage driver to classify non-performance-critical IOs as "low"
75	* priority. Separate updates are expected for low/high priority IOs.
76	*/
77
78	#define IO_PRIORITY_LOW (0x1ULL << 8)
79
80	/* Reserved for estimates of bursts of future IOs; could possibly benefit from
81	* a time horizon, but it's unclear if it will be specifiable by any layer with
82	* reasonable accuracy
83	*/
84	#define IO_PRIORITY_PREDICTIVE (0x1ULL << 16)
85
86	uint64_t io_rate_update(
87	uint64_t io_rate_flags, /* Rotating/NAND, IO priority level */
88	uint64_t read_ops_delta,
89	uint64_t write_ops_delta,
90	uint64_t read_bytes_delta,
91	uint64_t write_bytes_delta);
92
93	typedef uint64_t (*io_rate_update_callback_t) (uint64_t, uint64_t, uint64_t, uint64_t, uint64_t);
94
95	void io_rate_update_register(io_rate_update_callback_t);
96
3e170ce0 A	97	/* Interfaces for integrated GPUs to supply command submission telemetry.
	98	*/
	99
	100	#define GPU_NCMDS_VALID (0x1)
	101	#define GPU_NOUTSTANDING_VALID (0x2)
	102	#define GPU_BUSY_VALID (0x4)
	103	#define GPU_CYCLE_COUNT_VALID (0x8)
	104	#define GPU_MISC_VALID (0x10)
	105
	106	void gpu_submission_telemetry(
	107	uint64_t gpu_ncmds_total,
	108	uint64_t gpu_noutstanding,
	109	uint64_t gpu_busy_ns_total,
	110	uint64_t gpu_cycles,
	111	uint64_t gpu_telemetry_valid_flags,
	112	uint64_t gpu_telemetry_misc);
	113
	114	typedef uint64_t (*gpu_set_fceiling_t) (uint32_t gpu_fceiling_ratio, uint64_t gpu_fceiling_param);
	115
	116	void gpu_fceiling_cb_register(gpu_set_fceiling_t);
	117
fe8ab488 A	118	__END_DECLS
	119	#endif /* KERNEL */
	120
	121	#endif /* _KERN_ENERGY_PERF_H_ */