Document changes in behaviour due to sparse CPU numbering support.
This commit is contained in:
parent
122ccdc1ca
commit
6455febbea
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=183267
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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 ,
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user