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 <sys/cdefs.h> 39 40 #include <stdint.h> 41 42 #include <kern/kern_types.h> 43 #include <mach/mach_types.h> 44 45 #ifdef KERNEL 46 __BEGIN_DECLS 47 48 typedef struct { 49 uint32_t gpu_id; 50 uint32_t gpu_max_domains; 51 } gpu_descriptor; 52 53 typedef gpu_descriptor *gpu_descriptor_t; 54 /* The GPU is expected to describe itself with this interface prior to reporting 55 * resource usage. 56 */ 57 void gpu_describe(gpu_descriptor_t); 58 59 #define GPU_SCOPE_CURRENT_THREAD (0x1) 60 #define GPU_SCOPE_MISC (0x2) 61 62 /* GPU utilisation update for the current thread. */ 63 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); 64 65 66 #ifdef KERNEL_PRIVATE 67 68 #define SUPPORT_ENERGY_ID_REPORT_ENERGY 1 69 70 /* 71 * An energy id is an unreferenced unique identifier 72 * that can be used to account energy to a previously identified kernel object 73 * without having to hold a reference on it. That kernel object may become 74 * terminated before this energy ID is used. 75 * 76 * As an implementation detail, this may be an identifier for a resource 77 * coalition or a task. 78 * 79 * Prefer to use accounting interfaces through IOPerfControl instead, unless 80 * energy data is not available immediately after a work item is complete. 81 */ 82 typedef uint64_t energy_id_t; 83 84 /*! 85 * @function current_energy_id() 86 * 87 * @abstract 88 * Produces an energy id that the current context should account to. 89 * 90 * @param energy_id energy id for the current context 91 * 92 * @returns KERN_SUCCESS An energy id is produced 93 * KERN_FAILURE The current task is kernel_task or doesn't support accounting. 94 */ 95 extern kern_return_t 96 current_energy_id(energy_id_t *energy_id); 97 98 /*! 99 * @function task_id_token_to_energy_id() 100 * 101 * @abstract 102 * Produces an energy id from a task identity token port name found 103 * in the current task's IPC space. (e.g. from task_create_identity_token) 104 * 105 * This does a task identity port to task_t translation via proc_find_ident, 106 * which may stall while the targeted task is execing. 107 * 108 * @param name port name for the task identity token to operate on 109 * @param energy_id energy id for the provided task 110 * 111 * @returns KERN_SUCCESS A valid energy id is produced 112 * KERN_INVALID_ARGUMENT Passed identity token is invalid 113 * KERN_NOT_FOUND Cannot find task represented by token 114 */ 115 extern kern_return_t 116 task_id_token_to_energy_id(mach_port_name_t name, energy_id_t *energy_id); 117 118 #define ENERGY_ID_NONE (0x0) 119 120 __enum_decl(energy_id_source_t, uint32_t, { 121 ENERGY_ID_SOURCE_GPU = 1, 122 }); 123 124 /*! 125 * @function energy_id_report_energy() 126 * 127 * @abstract 128 * Report energy use for an energy ID. 129 * Optionally, report that this energy use was done on behalf of another 130 * energy ID, which can be the same ID. 131 * To indicate that the energy use is not on behalf of any other ID, provide 132 * ENERGY_ID_NONE for the on_behalf_of_id. 133 * 134 * If the primary and secondary IDs refer to the same entity, then energy 135 * will be reported as work it did on behalf of itself (it will not be double 136 * counted) 137 * 138 * If the provided primary ID is no longer valid, energy use will either be ignored 139 * or accounted to a global 'dead' accounting bucket. 140 * If the secondary ID is no longer valid, energy use will still be reported 141 * in the 'on behalf of' field of the primary, and will either be ignored or 142 * accounted to the global 'dead' bucket's on behalf of field. 143 * 144 * Note that the energy ID may still be valid temporarily after energy data has been 145 * snapshotted by launchd for reporting to powerlog, so energy accounted during 146 * this window may be lost. 147 * 148 * @param energy_source what HW entity used the energy 149 * @param self_id energy ID for the entity directly responsible for this work 150 * @param on_behalf_of_id energy ID for the entity that this work was done on behalf of 151 * @param energy energy to report in nanojoules 152 * 153 * @returns KERN_SUCCESS Energy accounting accepted 154 * KERN_INVALID_ARGUMENT The entity identified by self_id is invalid 155 * KERN_NOT_FOUND The entity identified by self_id doesn't exist 156 * KERN_NOT_SUPPORTED Unknown type of energy_source 157 */ 158 extern kern_return_t 159 energy_id_report_energy(energy_id_source_t energy_source, energy_id_t self_id, 160 energy_id_t on_behalf_of_id, uint64_t energy); 161 162 #endif /* KERNEL_PRIVATE */ 163 164 /* Interfaces for the block storage driver to advise the perf. controller of 165 * recent IOs 166 */ 167 168 /* Target medium for this set of IOs. Updates can occur in parallel if 169 * multiple devices exist, hence consumers must synchronize internally, ideally 170 * in a low-overhead fashion such as per-CPU counters, as this may be invoked 171 * within the IO path. 172 */ 173 174 #define IO_MEDIUM_ROTATING (0x0ULL) 175 #define IO_MEDIUM_SOLID_STATE (0x1ULL) 176 177 /* As there are several priority bands whose nature is evolving, we rely on the 178 * block storage driver to classify non-performance-critical IOs as "low" 179 * priority. Separate updates are expected for low/high priority IOs. 180 */ 181 182 #define IO_PRIORITY_LOW (0x1ULL << 8) 183 184 /* Reserved for estimates of bursts of future IOs; could possibly benefit from 185 * a time horizon, but it's unclear if it will be specifiable by any layer with 186 * reasonable accuracy 187 */ 188 #define IO_PRIORITY_PREDICTIVE (0x1ULL << 16) 189 190 uint64_t io_rate_update( 191 uint64_t io_rate_flags, /* Rotating/NAND, IO priority level */ 192 uint64_t read_ops_delta, 193 uint64_t write_ops_delta, 194 uint64_t read_bytes_delta, 195 uint64_t write_bytes_delta); 196 197 typedef uint64_t (*io_rate_update_callback_t) (uint64_t, uint64_t, uint64_t, uint64_t, uint64_t); 198 199 void io_rate_update_register(io_rate_update_callback_t); 200 201 /* Interfaces for integrated GPUs to supply command submission telemetry. 202 */ 203 204 #define GPU_NCMDS_VALID (0x1) 205 #define GPU_NOUTSTANDING_VALID (0x2) 206 #define GPU_BUSY_VALID (0x4) 207 #define GPU_CYCLE_COUNT_VALID (0x8) 208 #define GPU_MISC_VALID (0x10) 209 210 void gpu_submission_telemetry( 211 uint64_t gpu_ncmds_total, 212 uint64_t gpu_noutstanding, 213 uint64_t gpu_busy_ns_total, 214 uint64_t gpu_cycles, 215 uint64_t gpu_telemetry_valid_flags, 216 uint64_t gpu_telemetry_misc); 217 218 typedef uint64_t (*gpu_set_fceiling_t) (uint32_t gpu_fceiling_ratio, uint64_t gpu_fceiling_param); 219 220 void gpu_fceiling_cb_register(gpu_set_fceiling_t); 221 222 __END_DECLS 223 #endif /* KERNEL */ 224 225 #endif /* _KERN_ENERGY_PERF_H_ */ 226