A first cut at teaching libkvm how to deal with dynamic per-CPU storage

(DPCPU):

A new API, kvm_dpcpu_setcpu(3), selects the active CPU for the purposes
of DPCPU.  Calls to kvm_nlist(3) will automatically translate DPCPU
symbols and return a pointer to the current CPU's version of the data.
Consumers needing to read the same symbol on several CPUs will invoke a
series of setcpu/nlist calls, one per CPU of interest.

This addition makes it possible for tools like netstat(1) to query the
values of DPCPU variables during crashdump analysis, and is based on
similar code handling virtualized global variables.

MFC after:	1 week
Sponsored by:	Juniper Networks, Inc.

1 files changed, 33 insertions, 4 deletions

diff --git a/lib/libkvm/kvm_getpcpu.3 b/lib/libkvm/kvm_getpcpu.3
index 40f16ac..f2deda9 100644
--- a/lib/libkvm/kvm_getpcpu.3
+++ b/lib/libkvm/kvm_getpcpu.3
@@ -28,10 +28,11 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 19, 2008
+.Dd February 28, 2010
 .Dt KVM_GETPCPU 3
 .Os
 .Sh NAME
+.Nm kvm_dpcpu_setcpu
 .Nm kvm_getmaxcpu ,
 .Nm kvm_getpcpu
 .Nd access per-CPU data
@@ -43,20 +44,30 @@
 .In sys/sysctl.h
 .In kvm.h
 .Ft int
+.Fn kvm_dpcpu_setcpu "kvm_t *kd" "u_int cpu"
+.Ft int
 .Fn kvm_getmaxcpu "kvm_t *kd"
 .Ft void *
 .Fn kvm_getpcpu "kvm_t *kd" "int cpu"
 .Sh DESCRIPTION
 The
-.Fn kvm_getmaxcpu
+.Fn kvm_dpcpu_setcpu ,
+.Fn kvm_getmaxcpu ,
 and
 .Fn kvm_getpcpu
 functions are used to access the per-CPU data of active processors in the
 kernel indicated by
 .Fa kd .
+Per-CPU storage comes in two flavours: data stored directly in a
+.Vt "struct pcpu"
+associated with each CPU, and dynamic per-CPU storage (DPCPU), in which a
+single kernel symbol refers to different data depending on what CPU it is
+accessed from.
+.Pp
 The
 .Fn kvm_getmaxcpu
 function returns the maximum number of CPUs supported by the kernel.
+.Pp
 The
 .Fn kvm_getpcpu
 function returns a buffer holding the per-CPU data for a single CPU.
@@ -71,8 +82,22 @@ If
 is not active, then
 .Dv NULL
 is returned instead.
+.Pp
+Symbols for dynamic per-CPU data are accessed via
+.Xr kvm_nlist 3
+as with other symbols.
+.Nm libkvm
+maintains a notion of the "current CPU", set by
+.Xr kvm_dpcpu_setcpu ,
+which defaults to 0.
+Once another CPU is selected,
+.Xr kvm_nlist 3
+will return pointers to that data on the appropriate CPU.
 .Sh CACHING
-These functions cache the nlist values for various kernel variables which are
+.Fn kvm_getmaxcpu
+and
+.Vn kvm_getpcpu
+cache the nlist values for various kernel variables which are
 reused in successive calls.
 You may call either function with
 .Fa kd
@@ -93,7 +118,11 @@ function returns a pointer to an allocated buffer or
 If an error occurs,
 it returns -1 instead.
 .Pp
-If either function encounters an error,
+On success, the
+.Fn kvm_dpcpu_setcpu
+call returns 0; if an error occurs, it returns -1 instead.
+.Pp
+If any function encounters an error,
 then an error message may be retrieved via
 .Xr kvm_geterr 3.
 .Sh SEE ALSO