kern/49265: struct uvmexp{,_sysctl} contents lightly documented

[dholland%eecs.harvard.edu@localhost]

>Number:         49265
>Category:       kern
>Synopsis:       struct uvmexp{,_sysctl} contents lightly documented
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Oct 09 20:10:00 +0000 2014
>Originator:     David A. Holland
>Release:        NetBSD 7.99.1 (20140819)
>Organization:
>Environment:
System: NetBSD macaran 7.99.1 NetBSD 7.99.1 (MACARAN) #21: Tue Aug 19 20:08:43 EDT 2014 dholland@macaran:/usr/src/sys/arch/amd64/compile/MACARAN amd64
Architecture: x86_64
Machine: amd64
>Description:

The fields in struct uvmexp and struct uvmexp_sysctl are only lightly
documented. They aren't mentioned at all in sysctl(7); some of them
are implicitly documented in vmstat(1) and systat(1) but that doesn't
really count. They are all at least mentioned in uvm(9); however, the
documentation there is limited to C&P of the comments from
uvm_extern.h, which are mostly adequate for kernel hackers but
entirely insufficient for system administrators or application
developers trying to get memory information.

The immediate problem I bumped into is trying to figure out how the
various space counters add up -- I would have thought, for example,
that the number of free, active, inactive, and zero pages should sum
to the number of managed pages; but it doesn't, it exceeds it (on this
machine, right now) by about 0.15%, and the number of this discrepancy
doesn't match any of the other counters in the structure.

It's also not clear how the filepages and execpages counters relate to
these numbers.

Two other related issues that should be fixed at the same time:

 * sysctl(7) does not document that new user code should use only
struct uvmexp_sysctl and its corresponding sysctl, not the old struct
uvmexp. I understand this to be the case from elsewhere, however.

 * In order to facilitate general understanding of this, probably the
field comments in uvm_extern.h should be moved from struct uvmexp to
struct uvmexp_sysctl. Or at least copied.

 * If you do 'sysctl vm.uvmexp2' it prints
   sysctl: vm.uvmexp2: use 'vmstat' or 'systat' to view this information
but it should probably (instead or also) make explicit mention of
vmstat -s, which has this specific purpose.

>How-To-Repeat:
as above
>Fix:
write write write