NetBSD Problem Report #49265

From mogget@macaran.localdomain  Thu Oct  9 20:10:00 2014
Return-Path: <mogget@macaran.localdomain>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
	(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
	(Client CN "mail.netbsd.org", Issuer "Postmaster NetBSD.org" (verified OK))
	by mollari.NetBSD.org (Postfix) with ESMTPS id C9536A664E
	for <gnats-bugs@gnats.NetBSD.org>; Thu,  9 Oct 2014 20:10:00 +0000 (UTC)
Message-Id: <20141009185338.3C0076E25C@macaran.localdomain>
Date: Thu,  9 Oct 2014 14:53:38 -0400 (EDT)
From: dholland@eecs.harvard.edu
Reply-To: dholland@eecs.harvard.edu
To: gnats-bugs@NetBSD.org
Subject: struct uvmexp{,_sysctl} contents lightly documented
X-Send-Pr-Version: 3.95

>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
>Last-Modified:  Sat Oct 11 02:05: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

>Audit-Trail:
From: David Holland <dholland-bugs@netbsd.org>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: kern/49265: struct uvmexp{,_sysctl} contents lightly documented
Date: Sat, 11 Oct 2014 02:00:41 +0000

 On Thu, Oct 09, 2014 at 08:10:06PM +0000, dholland@eecs.harvard.edu wrote:
  > Two other related issues that should be fixed at the same time:

 yeah, for values of "two" equal to "three", and here's a fourth:

 * The header file to get struct uvmexp_sysctl defined isn't documented.

 -- 
 David A. Holland
 dholland@netbsd.org

NetBSD Home
NetBSD PR Database Search

(Contact us) $NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.8 2006/05/07 09:23:38 tsutsui Exp $
Copyright © 1994-2014 The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.