#include <kern/energy_perf.h>
Kernel (KEXT) › kern/ primitives

kern/energy_perf.h Kernel.framework

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.
includes: sys/cdefs.h, Kernel/stdint.h, kern/kern_types.h, mach/mach_types.h
11 macros · 6 functions · 4 typedefs · 1 struct

structgpu_descriptor

size 8, align 4
uint32_tgpu_id
uint32_tgpu_max_domains

typedefgpu_descriptor

typedef struct gpu_descriptor gpu_descriptor;

typedefgpu_descriptor_t

typedef gpu_descriptor *gpu_descriptor_t

functiongpu_describe

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

macroGPU_SCOPE_CURRENT_THREAD

#define GPU_SCOPE_CURRENT_THREAD (0x1)

macroGPU_SCOPE_MISC

#define GPU_SCOPE_MISC (0x2)

functiongpu_accumulate_time

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
)
GPU utilisation update for the current thread.

macroIO_MEDIUM_ROTATING

#define IO_MEDIUM_ROTATING (0x0ULL)

macroIO_MEDIUM_SOLID_STATE

#define IO_MEDIUM_SOLID_STATE (0x1ULL)

macroIO_PRIORITY_LOW

#define IO_PRIORITY_LOW (0x1ULL << 8)

macroIO_PRIORITY_PREDICTIVE

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)

functionio_rate_update

uint64_t io_rate_update(
	/* Rotating/NAND, IO priority level */
	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
)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/energy_perf.c, osfmk/kern/energy_perf.h
Advises the performance controller of recent block-storage IO by invoking the callback installed with io_rate_update_register (the default callback returns 0). io_rate_flags describes the target medium and priority band (IO_MEDIUM_ROTATING or IO_MEDIUM_SOLID_STATE, IO_PRIORITY_LOW, IO_PRIORITY_PREDICTIVE); the remaining arguments are deltas of read/write operations and bytes since the previous update. May be invoked in the IO path, so consumers are expected to synchronize cheaply. Returns the callback's value.

typedefio_rate_update_callback_t

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

functionio_rate_update_register

void io_rate_update_register(io_rate_update_callback_t)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/energy_perf.c, osfmk/kern/energy_perf.h
Installs the callback invoked by io_rate_update, typically supplied by the performance controller (CLPC). Passing NULL restores the default callback, which ignores the update and returns 0.

macroGPU_NCMDS_VALID

#define GPU_NCMDS_VALID (0x1)

macroGPU_NOUTSTANDING_VALID

#define GPU_NOUTSTANDING_VALID (0x2)

macroGPU_BUSY_VALID

#define GPU_BUSY_VALID (0x4)

macroGPU_CYCLE_COUNT_VALID

#define GPU_CYCLE_COUNT_VALID (0x8)

macroGPU_MISC_VALID

#define GPU_MISC_VALID (0x10)

functiongpu_submission_telemetry

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
)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/energy_perf.c, osfmk/kern/energy_perf.h
Interface for integrated GPU drivers to supply command-submission telemetry: total commands submitted, outstanding commands, cumulative busy time in nanoseconds, GPU cycle count, and a miscellaneous field. gpu_telemetry_valid_flags marks which fields are valid (GPU_NCMDS_VALID, GPU_NOUTSTANDING_VALID, GPU_BUSY_VALID, GPU_CYCLE_COUNT_VALID, GPU_MISC_VALID). In this kernel the routine is an empty stub that discards the telemetry.

typedefgpu_set_fceiling_t

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

functiongpu_fceiling_cb_register

void gpu_fceiling_cb_register(gpu_set_fceiling_t)
▾
claude-fable-5, 2026-08-24 · not from Apple sources · verified against xnu osfmk/kern/energy_perf.c, osfmk/kern/energy_perf.h
Installs the gpu_set_fceiling_t callback through which the kernel requests a GPU frequency ceiling (ratio plus parameter). Passing NULL restores the default callback, which does nothing and returns 0.