lib/libpmc/pmc_get_msr.3

   1 .\" Copyright (c) 2007 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 THE AUTHOR AND CONTRIBUTORS ``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 THE AUTHOR OR CONTRIBUTORS 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 .Dd November 25, 2007
  25 .Dt PMC_GET_MSR 3
  26 .Os
  27 .Sh NAME
  28 .Nm pmc_get_msr
  29 .Nd x86 architecture-specific PMC operations
  30 .Sh LIBRARY
  31 .Lb libpmc
  32 .Sh SYNOPSIS
  33 .In pmc.h
  34 .Ft int
  35 .Fn pmc_get_msr "pmc_id_t pmc" "uint32_t *msr"
  36 .Sh DESCRIPTION
  37 The function
  38 .Fn pmc_get_msr
  39 returns the processor model specific register number associated with
  40 a PMC for subsequent use with RDPMC instructions.
  41 Argument
  42 .Fa pmc
  43 specifies a process scope counting PMC.
  44 The function will write the model specific register number associated
  45 with the PMC to the location pointed to by argument
  46 .Fa msr .
  47 .Pp
  48 After successful completion of this function, applications
  49 can directly read the contents of PMC hardware using
  50 RDPMC instructions.
  51 .Sh RETURN VALUES
  52 .Rv -std pmc_get_msr
  53 .Sh ERRORS
  54 A call to
  55 .Fn pmc_get_msr
  56 may fail with the following errors:
  57 .Bl -tag -width Er
  58 .It Bq Er EINVAL
  59 The PMC handle specified was invalid.
  60 .It Bq Er EINVAL
  61 The PMC specified did not have process scope or counting mode.
  62 .It Bq Er EINVAL
  63 The PMC specified was allocated with the
  64 .Dv PMC_F_DESCENDANTS
  65 flag.
  66 .It Bq Er EINVAL
  67 The specified PMC is already attached to target processes other
  68 than the owner.
  69 .It Bq Er ENOSYS
  70 The underlying hardware does not support an RDPMC instruction.
  71 .El
  72 .Sh SEE ALSO
  73 .Xr pmc 3 ,
  74 .Xr hwpmc 4