d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document changes in behaviour due to sparse CPU numbering support.

Browse Source
This commit is contained in:
Joseph Koshy 2008-09-22 14:31:24 +00:00
parent 122ccdc1ca
commit 6455febbea
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=183267
6 changed files with 46 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
lib/libpmc/pmc.3
View File

@ -261,7 +261,14 @@ CPU is running unprivileged code.
.It Li PMC_CAP_WRITE
The ability to write to performance counters.
.El
.Ss Functional Grouping
.Ss CPU Naming Conventions
CPUs are named using small integers from zero uptil, but
excluding, the value returned by function
.Fn pmc_ncpu .
On platforms supporting sparsely numbered CPUs not all the numbers in
this range will denote valid CPUs.
Operations on non-existent CPUs will return an error.
.Ss Functional Grouping of the API
This section contains a brief overview of the available functionality
in the PMC library.
Each function listed here is described further in its own manual page.
@ -342,7 +349,7 @@ system.
Retrieve statistics maintained by
.Xr hwpmc 4 .
.It Fn pmc_ncpu
Determine the number of CPUs in the system.
Determine the greatest possible CPU number on the system.
.It Fn pmc_npmc
Return the number of hardware PMCs present in a given CPU.
.It Fn pmc_pmcinfo

6
lib/libpmc/pmc_allocate.3
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
.\" Copyright (c) 2007-2008 Joseph Koshy. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@ -23,7 +23,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd November 20, 2007
.Dd September 22, 2008
.Os
.Dt PMC_ALLOCATE 3
.Sh NAME
@ -156,7 +156,7 @@ error.
.It Bq Er ENXIO
Function
.Fn pmc_allocate
requested the use of a hardware resource that was previously
requested the use of a hardware resource that was absent or
administratively disabled.
.It Bq Er EOPNOTSUPP
The underlying hardware does not support the capabilities needed for

15
lib/libpmc/pmc_capabilities.3
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
.\" Copyright (c) 2007-2008 Joseph Koshy. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@ -23,7 +23,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd November 24, 2007
.Dd September 22, 2008
.Os
.Dt PMC_CAPABILITIES 3
.Sh NAME
@ -96,8 +96,11 @@ in the system.
.Pp
Function
.Fn pmc_ncpu
is a convenience function that returns the number of CPUs in the
system.
is a convenience function that returns the maximum CPU number in
the system.
On systems that support sparsely numbered CPUs, not all CPUs may
be physically present.
Applications need to be prepared to deal with nonexistent CPUs.
.Pp
Function
.Fn pmc_npmc
@ -201,11 +204,11 @@ may fail with the following errors:
.It Bq Er EINVAL
The argument
.Fa cpu
specified a non-existent CPU.
was invalid.
.It Bq Er ENXIO
The argument
.Fa cpu
specified a disabled CPU.
specified a disabled or absent CPU.
.El
.Pp
A call to function

8
lib/libpmc/pmc_disable.3
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
.\" Copyright (c) 2007-2008 Joseph Koshy. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@ -23,7 +23,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd November 20, 2007
.Dd September 22, 2008
.Os
.Dt PMC_ENABLE 3
.Sh NAME
@ -85,7 +85,7 @@ were invalid.
.It Bq Er ENXIO
Argument
.Fa cpu
specified a disabled CPU.
specified a disabled or absent CPU.
.It Bq Er EPERM
The current process lacks sufficient privilege to perform this
operation.
@ -96,4 +96,4 @@ operation.
.Xr pmc_pmcinfo 3 ,
.Xr hwpmc 4 ,
.Xr pmccontrol 8 ,
.Xr priv_check 9
.Xr priv_check 9

7
lib/libpmc/pmc_start.3
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
.\" Copyright (c) 2007-2008 Joseph Koshy. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@ -23,7 +23,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd November 25, 2007
.Dd September 22, 2008
.Os
.Dt PMC_START 3
.Sh NAME
@ -69,7 +69,8 @@ Function
.Fn pmc_stop
specified a PMC that was never started.
.It Bq Er ENXIO
The specified PMC had system scope and its associated CPU was disabled.
The specified PMC had system scope and its associated CPU was disabled or
absent.
.El
.Sh SEE ALSO
.Xr pmc 3 ,

26
share/man/man4/hwpmc.4
View File

@ -1,4 +1,4 @@
.\" Copyright (c) 2003-2007 Joseph Koshy
.\" Copyright (c) 2003-2008 Joseph Koshy
.\" Copyright (c) 2007 The FreeBSD Foundation
.\" All rights reserved.
.\"
@ -28,7 +28,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd November 24, 2007
.Dd September 22, 2008
.Dt HWPMC 4
.Os
.Sh NAME
@ -307,8 +307,8 @@ has returned.
The returned error code reflects any pending error state inside
.Nm .
.It Dv PMC_OP_GETCPUINFO
Retrieve information about the number of CPUs on the system and
the number of hardware performance monitoring counters available per-CPU.
Retrieve information about the highest possible CPU number for the system,
and the number of hardware performance monitoring counters available per CPU.
.It Dv PMC_OP_GETDRIVERSTATS
Retrieve module statistics (for analyzing the behavior of
.Nm
@ -490,6 +490,12 @@ via the RDTSC instruction.
.Ss SMP Symmetry
The kernel driver requires all physical CPUs in an SMP system to have
identical performance monitoring counter hardware.
.Ss Sparse CPU Numbering
On platforms that sparsely number CPUs and which support hot-plugging
of CPUs, requests that specify non-existent or disabled CPUs will fail
with an error.
Applications allocating system-scope PMCs need to be aware of
the possibility of such transient failures.
.Ss x86 TSC Handling
Historically, on the x86 architecture,
.Fx
@ -735,17 +741,19 @@ PMCs directly with the RDPMC instruction.
.It Bq Er ENXIO
A
.Dv PMC_OP_GETPMCINFO
operation was requested for a disabled CPU.
operation was requested for an absent or disabled CPU.
.It Bq Er ENXIO
A system-wide PMC on a disabled CPU was requested to be allocated with
.Dv PMC_OP_PMCALLOCATE .
A
.Dv PMC_OP_PMCALLOCATE
operation specified allocation of a system-wide PMC on an absent or
disabled CPU.
.It Bq Er ENXIO
A
.Dv PMC_OP_PMCSTART
or
.Dv PMC_OP_PMCSTOP
request was issued for a system-wide PMC that was allocated on a
currently disabled CPU.
request was issued for a system-wide PMC that was allocated on a CPU
that is currently absent or disabled.
.It Bq Er EOPNOTSUPP
A
.Dv PMC_OP_PMCALLOCATE