lib/libarch/i386/i386_pmc_info.2

   1 .\"     $NetBSD: i386_pmc_info.2,v 1.10 2005/12/26 19:40:14 perry Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Gregory McGarry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd November 10, 2001
  31 .Dt I386_PMC_INFO 2 i386
  32 .Os
  33 .Sh NAME
  34 .Nm i386_pmc_info ,
  35 .Nm i386_pmc_startstop ,
  36 .Nm i386_pmc_read
  37 .Nd interface to CPU performance counters
  38 .Sh LIBRARY
  39 .Lb libi386
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In machine/sysarch.h
  43 .In machine/specialreg.h
  44 .Ft int
  45 .Fn i386_pmc_info "struct i386_pmc_info_args *ia"
  46 .Ft int
  47 .Fn i386_pmc_startstop "struct i386_pmc_startstop_args *ssa"
  48 .Ft int
  49 .Fn i386_pmc_read "struct i386_pmc_read_args *ra"
  50 .Sh DESCRIPTION
  51 These functions provide an interface to the CPU performance counters
  52 on the 586-class and 686-class processors.
  53 .Pp
  54 .Fn i386_pmc_info
  55 will return information about the available CPU counters.
  56 The information is returned in
  57 .Fa ia
  58 having the following structure:
  59 .Bd -literal
  60 struct i386_pmc_info_args {
  61         int     type;
  62         int     flags;
  63 };
  64 .Ed
  65 .Pp
  66 The
  67 .Em type
  68 member describes the class of performance counters available.
  69 Valid values are:
  70 .Pp
  71 .Bl -tag -offset indent -width PMC_INFO_HASTSC -compact
  72 .It PMC_TYPE_NONE
  73 No PMC support
  74 .It PMC_TYPE_I586
  75 586-class CPUs
  76 .It PMC_TYPE_I686
  77 686-class Intel CPUs
  78 .It PMC_TYPE_K7
  79 686-class AMD CPUs
  80 .El
  81 .Pp
  82 The
  83 .Em flags
  84 member describes additional capabilities of the processor.
  85 Valid values are:
  86 .Pp
  87 .Bl -tag -offset indent -width PMC_INFO_HASTSC -compact
  88 .It PMC_INFO_HASTSC
  89 CPU has time-stamp counter
  90 .El
  91 .Pp
  92 .Fn i386_pmc_startstop
  93 is used to start and stop the measurement of the CPU performance counters.
  94 The argument
  95 .Fa ssa
  96 has the following structure:
  97 .Bd -literal
  98 struct i386_pmc_startstop_args {
  99         int counter;
 100         uint64_t val;
 101         uint8_t event;
 102         uint8_t unit;
 103         uint8_t compare;
 104         uint8_t flags;
 105 };
 106 .Ed
 107 .Pp
 108 The counter specified by the member
 109 .Em counter
 110 is started if the member
 111 .Em flags
 112 has PMC_SETUP_KERNEL or PMC_SETUP_USER set, otherwise the counter is
 113 stopped.
 114 The initial value of the counter is set to
 115 .Em val .
 116 Additional values for the
 117 .Em flags
 118 member are PMC_SETUP_EDGE and PMC_SETUP_INV.
 119 The
 120 .Em event
 121 member specifies some event written to the control register.
 122 The
 123 .Em unit
 124 member specifies the measurement units.
 125 The
 126 .Em compare
 127 member is a mask for the counter.
 128 .Pp
 129 .Fn i386_pmc_read
 130 will return information about a specific CPU counter measured during
 131 the last measurement period determined by the calling of
 132 .Fn i386_pmc_startstop .
 133 The information is returned in
 134 .Fa ra
 135 having the following structure:
 136 .Bd -literal
 137 struct i386_pmc_read_args {
 138         int counter;
 139         uint64_t val;
 140         uint64_t time;
 141 };
 142 .Ed
 143 .Pp
 144 The counter to read should be specified by the
 145 .Em counter
 146 member.
 147 Counters are numbered from 0 to
 148 .Dv PMC_NCOUNTERS .
 149 The value of the counter is returned in the
 150 .Em val
 151 member.
 152 The time since epoch, measured in CPU clock cycles, is returned in the
 153 .Em time
 154 member.
 155 .Sh RETURN VALUES
 156 Upon successful completion zero is returned, otherwise \-1 is returned
 157 on failure.