[apple/xnu.git] / bsd / man / man9 / monotonic.9

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