bsd/man/man9/monotonic.9

   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