usr.sbin/pmccontrol/pmccontrol.8

   1 .\" Copyright (c) 2003,2008 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" This software is provided by Joseph Koshy ``as is'' and
  13 .\" any express or implied warranties, including, but not limited to, the
  14 .\" implied warranties of merchantability and fitness for a particular purpose
  15 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  17 .\" damages (including, but not limited to, procurement of substitute goods
  18 .\" or services; loss of use, data, or profits; or business interruption)
  19 .\" however caused and on any theory of liability, whether in contract, strict
  20 .\" liability, or tort (including negligence or otherwise) arising in any way
  21 .\" out of the use of this software, even if advised of the possibility of
  22 .\" such damage.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd November 9, 2008
  27 .Dt PMCCONTROL 8
  28 .Os
  29 .Sh NAME
  30 .Nm pmccontrol
  31 .Nd "control hardware performance monitoring counters"
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Oo Fl c Ar cpu | Fl d Ar pmc | Fl e Ar pmc Oc ...
  35 .Nm
  36 .Fl l
  37 .Nm
  38 .Fl L
  39 .Nm
  40 .Fl s
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 utility controls the operation of the system's hardware performance
  45 monitoring counters.
  46 .Sh OPTIONS
  47 The
  48 .Nm
  49 utility processes options in command line order, so later options modify
  50 the effect of earlier ones.
  51 The following options are available:
  52 .Bl -tag -width indent
  53 .It Fl c Ar cpu
  54 Subsequent enable and disable options affect the CPU
  55 denoted by argument
  56 .Ar cpu .
  57 The argument
  58 .Ar cpu
  59 is a number denoting a CPU in the system, or
  60 .Dq Li * ,
  61 denoting all unhalted CPUs in the system.
  62 .It Fl d Ar pmc
  63 Disable PMC number
  64 .Ar pmc
  65 on the CPU specified by
  66 .Fl c ,
  67 preventing it from being used till subsequently re-enabled.
  68 The argument
  69 .Ar pmc
  70 is a number denoting a specific PMC, or
  71 .Dq Li *
  72 denoting all the PMCs on the specified CPU.
  73 .Pp
  74 Only idle PMCs may be disabled.
  75 .\" XXX this probably needs to be fixed.
  76 .It Fl e Ar pmc
  77 Enable PMC number
  78 .Ar pmc ,
  79 on the CPU specified by
  80 .Fl c ,
  81 allowing it to be used in the future.
  82 The argument
  83 .Ar pmc
  84 is a number denoting a specific PMC, or
  85 .Dq Li *
  86 denoting all the PMCs on the specified CPU.
  87 If PMC
  88 .Ar pmc
  89 is already enabled, this option has no effect.
  90 .It Fl l
  91 List available hardware performance counters and their current
  92 disposition.
  93 .It Fl L
  94 List available hardware performance counter classes and their
  95 supported event names.
  96 .It Fl s
  97 Print driver statistics maintained by
  98 .Xr hwpmc 4 .
  99 .El
 100 .Sh EXAMPLES
 101 To disable all PMCs on all CPUs, use the command:
 102 .Dl "pmccontrol -d*"
 103 .Pp
 104 To enable all PMCs on all CPUs, use:
 105 .Dl "pmccontrol -e*"
 106 .Pp
 107 To disable PMCs 0 and 1 on CPU 2, use:
 108 .Dl "pmccontrol -c2 -d0 -d1"
 109 .Pp
 110 To disable PMC 0 of CPU 0 only, and enable all other PMCS on all other
 111 CPUs, use:
 112 .Dl "pmccontrol -c* -e* -c0 -d0"
 113 .Sh DIAGNOSTICS
 114 .Ex -std
 115 .Sh SEE ALSO
 116 .Xr pmc 3 ,
 117 .Xr pmclog 3 ,
 118 .Xr hwpmc 4 ,
 119 .Xr pmcstat 8 ,
 120 .Xr sysctl 8
 121 .Sh HISTORY
 122 The
 123 .Nm
 124 utility first appeared in
 125 .Fx 6.0 .
 126 .Sh AUTHORS
 127 .An Joseph Koshy Aq jkoshy@FreeBSD.org