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
43typedef struct {
44 uint32_t gpu_id;
45 uint32_t gpu_max_domains;
46} gpu_descriptor;
47
48typedef gpu_descriptor *gpu_descriptor_t;
49/* The GPU is expected to describe itself with this interface prior to reporting
50 * resource usage.
51 */
52void 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. */
58uint64_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
86uint64_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
93typedef uint64_t (*io_rate_update_callback_t) (uint64_t, uint64_t, uint64_t, uint64_t, uint64_t);
94
95void io_rate_update_register(io_rate_update_callback_t);
96
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
106void 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
114typedef uint64_t (*gpu_set_fceiling_t) (uint32_t gpu_fceiling_ratio, uint64_t gpu_fceiling_param);
115
116void gpu_fceiling_cb_register(gpu_set_fceiling_t);
117
118__END_DECLS
119#endif /* KERNEL */
120
121#endif /* _KERN_ENERGY_PERF_H_ */
122