osfmk/kern/energy_perf.h

   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
  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
 118 __END_DECLS
 119 #endif /* KERNEL */
 120
 121 #endif /* _KERN_ENERGY_PERF_H_ */