1.\" Copyright (c) 2017, Apple Inc. All rights reserved. 2.\" 3.Dd March 1, 2017 4.Dt MONOTONIC 9 5.Os Darwin 6.\" 7.Sh NAME 8.Nm monotonic 9.Nd performance counter access system 10.\" 11.Sh DESCRIPTION 12.Nm 13allows kernel and user space clients to configure and read hardware performance 14counters. The hardware counters can be virtualized to count per-thread and 15per-process. 16.Nm 17is split into three major layers: 18.Bl -dash 19.It 20The machine-dependent implementations manipulate hardware registers to configure 21and access the counters. This layer provides a machine-independent interface 22that can be used by the next layer. 23.It 24A set of hooks and kernel routines manage the counters and provide higher-level 25abstractions, like 64-bit counters and counting only events that occurred on a 26thread or in a process. 27.It 28A user space interface that is presented as device nodes under 29.Pa /dev/monotonic . 30See 31.Xr monotonic 4 . 32Mach thread and task ports are used for the per-thread and per-process counts, 33with special inspection routines. Some counter values are also reflected into 34.Fn getrusage , 35for use after a process has exited. See 36.Xr getrusage 2 . 37.El 38.Pp 39.\".Sh DIAGNOSTICS 40.\" 41.Sh SEE ALSO 42.Xr count 1 , 43.Xr mperf 1 , 44.Xr easyperf 1 , 45.Xr getrusage 2 , 46.Xr monotonic 4 , 47.Xr perf 1 48.\" 49.Sh HISTORY 50.Nm 51replaces the kernel performance counter system, kpc. For the time being, 52.Nm 53backs portions of the existing kpc 54.Fn sysctl 55interface. Prior to kpc, the AppleProfileFamily kernel extensions provided 56performance counter interfaces. The kernel extensions themselves expanded upon 57functionality provided for PowerPC by CHUD. 58.\".Sh CAVEATS 59.\" 60.Sh SECURITY CONSIDERATIONS 61.Pp 62.Pp 63.Bl -dash 64.It 65Hardware performance counters are an ideal tool for side-channel attacks. By 66observing how the counters are affected by an otherwise opaque process, an 67attacker can obtain sensitive data or key material. 68.Pp 69For this reason, the hardware performance counters cannot be queried directly 70from user space. Instead, all processes, including those owned by root, can 71only query the thread and process counters if they have the corresponding Mach 72thread or task port. 73.It 74When used in sampling mode, hardware performance counters can induce interrupt 75storms that translate to denial-of-service attacks on a system. Even a careless 76user can stumble over this issue, since reasonable periods for some events are 77far too aggressive for others. 78.Pp 79If a hardware performance counter takes too many interrupts in a short amount of 80time, it will be disabled. 81.El 82