FreeBSD Mail Archives

Date:      Sat, 17 Jul 2010 11:02:51 GMT
From:      Galimov Albert <wtfcrap@mail.ru>
To:        freebsd-gnats-submit@FreeBSD.org
Subject:   kern/148710: [sysctl][patch] Document sys/kern sysctls
Message-ID:  <201007171102.o6HB2pR3045403@www.freebsd.org>
Resent-Message-ID: <201007171110.o6HBA3O3082686@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help


>Number:         148710
>Category:       kern
>Synopsis:       [sysctl][patch] Document sys/kern sysctls
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-bugs
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sat Jul 17 11:10:02 UTC 2010
>Closed-Date:
>Last-Modified:
>Originator:     Galimov Albert
>Release:        HEAD
>Organization:
>Environment:
>Description:
Descriptions for sysctls from sys/kern/sysv_sem.c sys/kern/kern_proc.c sys/kern/subr_clock.c sys/kern/kern_tc.c sys/kern/subr_rtc.c sys/kern/vfs_cache.c
>How-To-Repeat:

>Fix:
patch

Patch attached with submission follows:

Index: sys/kern/sysv_sem.c
===================================================================
--- sys/kern/sysv_sem.c	(revision 210019)
+++ sys/kern/sysv_sem.c	(working copy)
@@ -212,7 +212,7 @@
 SYSCTL_INT(_kern_ipc, OID_AUTO, semaem, CTLFLAG_RW, &seminfo.semaem, 0,
     "Adjust on exit max value");
 SYSCTL_PROC(_kern_ipc, OID_AUTO, sema, CTLFLAG_RD,
-    NULL, 0, sysctl_sema, "", "");
+    NULL, 0, sysctl_sema, "", "semaphore id pool");
 
 static struct syscall_helper_data sem_syscalls[] = {
 	SYSCALL_INIT_HELPER(__semctl),
Index: sys/kern/kern_proc.c
===================================================================
--- sys/kern/kern_proc.c	(revision 210019)
+++ sys/kern/kern_proc.c	(working copy)
@@ -148,7 +148,7 @@
 uma_zone_t proc_zone;
 
 int kstack_pages = KSTACK_PAGES;
-SYSCTL_INT(_kern, OID_AUTO, kstack_pages, CTLFLAG_RD, &kstack_pages, 0, "");
+SYSCTL_INT(_kern, OID_AUTO, kstack_pages, CTLFLAG_RD, &kstack_pages, 0, "KSTACK_PAGES is the number of memory pages to assigned to the kernel");
 
 CTASSERT(sizeof(struct kinfo_proc) == KINFO_PROC_SIZE);
 #ifdef COMPAT_FREEBSD32
Index: sys/kern/subr_clock.c
===================================================================
--- sys/kern/subr_clock.c	(revision 210019)
+++ sys/kern/subr_clock.c	(working copy)
@@ -61,7 +61,7 @@
  * kern.
  */
 SYSCTL_INT(_machdep, OID_AUTO, wall_cmos_clock,
-	CTLFLAG_RW, &wall_cmos_clock, 0, "");
+	CTLFLAG_RW, &wall_cmos_clock, 0, "wall CMOS clock assumed if != 0");
 
 static int
 sysctl_machdep_adjkerntz(SYSCTL_HANDLER_ARGS)
@@ -74,7 +74,7 @@
 }
 
 SYSCTL_PROC(_machdep, OID_AUTO, adjkerntz, CTLTYPE_INT|CTLFLAG_RW,
-	&adjkerntz, 0, sysctl_machdep_adjkerntz, "I", "");
+	&adjkerntz, 0, sysctl_machdep_adjkerntz, "I", "local offset from GMT in seconds");
 
 /*--------------------------------------------------------------------*
  * Generic routines to convert between a POSIX date
Index: sys/kern/kern_tc.c
===================================================================
--- sys/kern/kern_tc.c	(revision 210019)
+++ sys/kern/kern_tc.c	(working copy)
@@ -101,7 +101,7 @@
 
 static int timestepwarnings;
 SYSCTL_INT(_kern_timecounter, OID_AUTO, stepwarnings, CTLFLAG_RW,
-    &timestepwarnings, 0, "");
+    &timestepwarnings, 0, "Log warnings");
 
 static void tc_windup(void);
 static void cpu_tick_calibrate(int);
@@ -556,7 +556,7 @@
 }
 
 SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING | CTLFLAG_RW,
-    0, 0, sysctl_kern_timecounter_hardware, "A", "");
+    0, 0, sysctl_kern_timecounter_hardware, "A", "Report or change the active timecounter hardware selected");
 
 
 /* Report or change the active timecounter hardware. */
@@ -579,7 +579,7 @@
 }
 
 SYSCTL_PROC(_kern_timecounter, OID_AUTO, choice, CTLTYPE_STRING | CTLFLAG_RD,
-    0, 0, sysctl_kern_timecounter_choice, "A", "");
+    0, 0, sysctl_kern_timecounter_choice, "A", "Report the active timecounter hardware detected");
 
 /*
  * RFC 2783 PPS-API implementation.
@@ -764,7 +764,7 @@
  */
 
 static int tc_tick;
-SYSCTL_INT(_kern_timecounter, OID_AUTO, tick, CTLFLAG_RD, &tc_tick, 0, "");
+SYSCTL_INT(_kern_timecounter, OID_AUTO, tick, CTLFLAG_RD, &tc_tick, 0, "approx. number of hardclock ticks in a millisecond");
 
 void
 tc_ticktock(void)
Index: sys/kern/subr_rtc.c
===================================================================
--- sys/kern/subr_rtc.c	(revision 210019)
+++ sys/kern/subr_rtc.c	(working copy)
@@ -66,7 +66,7 @@
 /* XXX: should be kern. now, it's no longer machdep.  */
 static int disable_rtc_set;
 SYSCTL_INT(_machdep, OID_AUTO, disable_rtc_set,
-	CTLFLAG_RW, &disable_rtc_set, 0, "");
+	CTLFLAG_RW, &disable_rtc_set, 0, "Disable write system time back to RTC");
 
 void
 clock_register(device_t dev, long res)	/* res has units of microseconds */
Index: sys/kern/vfs_cache.c
===================================================================
--- sys/kern/vfs_cache.c	(revision 210019)
+++ sys/kern/vfs_cache.c	(working copy)
@@ -126,18 +126,18 @@
 static LIST_HEAD(nchashhead, namecache) *nchashtbl;	/* Hash Table */
 static TAILQ_HEAD(, namecache) ncneg;	/* Hash Table */
 static u_long	nchash;			/* size of hash table */
-SYSCTL_ULONG(_debug, OID_AUTO, nchash, CTLFLAG_RD, &nchash, 0, "");
+SYSCTL_ULONG(_debug, OID_AUTO, nchash, CTLFLAG_RD, &nchash, 0, "size of hash table");
 static u_long	ncnegfactor = 16;	/* ratio of negative entries */
-SYSCTL_ULONG(_debug, OID_AUTO, ncnegfactor, CTLFLAG_RW, &ncnegfactor, 0, "");
-static u_long	numneg;			/* number of cache entries allocated */
-SYSCTL_ULONG(_debug, OID_AUTO, numneg, CTLFLAG_RD, &numneg, 0, "");
+SYSCTL_ULONG(_debug, OID_AUTO, ncnegfactor, CTLFLAG_RW, &ncnegfactor, 0, "ratio of negative entries");
+static u_long	numneg;			/* number of negative cache entries allocated */
+SYSCTL_ULONG(_debug, OID_AUTO, numneg, CTLFLAG_RD, &numneg, 0, "number of negative cache entries allocated");
 static u_long	numcache;		/* number of cache entries allocated */
-SYSCTL_ULONG(_debug, OID_AUTO, numcache, CTLFLAG_RD, &numcache, 0, "");
+SYSCTL_ULONG(_debug, OID_AUTO, numcache, CTLFLAG_RD, &numcache, 0, "number of cache entries allocated");
 static u_long	numcachehv;		/* number of cache entries with vnodes held */
-SYSCTL_ULONG(_debug, OID_AUTO, numcachehv, CTLFLAG_RD, &numcachehv, 0, "");
+SYSCTL_ULONG(_debug, OID_AUTO, numcachehv, CTLFLAG_RD, &numcachehv, 0, "number of cache entries with vnodes held");
 #if 0
 static u_long	numcachepl;		/* number of cache purge for leaf entries */
-SYSCTL_ULONG(_debug, OID_AUTO, numcachepl, CTLFLAG_RD, &numcachepl, 0, "");
+SYSCTL_ULONG(_debug, OID_AUTO, numcachepl, CTLFLAG_RD, &numcachepl, 0, "number of cache purge for leaf entries");
 #endif
 struct	nchstats nchstats;		/* cache effectiveness statistics */
 
@@ -174,31 +174,31 @@
 } while (0)
 
 static int	doingcache = 1;		/* 1 => enable the cache */
-SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, "");
+SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, "enable the cache");
 
 /* Export size information to userland */
 SYSCTL_INT(_debug_sizeof, OID_AUTO, namecache, CTLFLAG_RD, 0,
-	sizeof(struct namecache), "");
+	sizeof(struct namecache), "Export size information to userland");
 
 /*
  * The new name cache statistics
  */
 static SYSCTL_NODE(_vfs, OID_AUTO, cache, CTLFLAG_RW, 0, "Name cache statistics");
-#define STATNODE(mode, name, var) \
-	SYSCTL_ULONG(_vfs_cache, OID_AUTO, name, mode, var, 0, "");
-STATNODE(CTLFLAG_RD, numneg, &numneg);
-STATNODE(CTLFLAG_RD, numcache, &numcache);
-static u_long numcalls; STATNODE(CTLFLAG_RD, numcalls, &numcalls);
-static u_long dothits; STATNODE(CTLFLAG_RD, dothits, &dothits);
-static u_long dotdothits; STATNODE(CTLFLAG_RD, dotdothits, &dotdothits);
-static u_long numchecks; STATNODE(CTLFLAG_RD, numchecks, &numchecks);
-static u_long nummiss; STATNODE(CTLFLAG_RD, nummiss, &nummiss);
-static u_long nummisszap; STATNODE(CTLFLAG_RD, nummisszap, &nummisszap);
-static u_long numposzaps; STATNODE(CTLFLAG_RD, numposzaps, &numposzaps);
-static u_long numposhits; STATNODE(CTLFLAG_RD, numposhits, &numposhits);
-static u_long numnegzaps; STATNODE(CTLFLAG_RD, numnegzaps, &numnegzaps);
-static u_long numneghits; STATNODE(CTLFLAG_RD, numneghits, &numneghits);
-static u_long numupgrades; STATNODE(CTLFLAG_RD, numupgrades, &numupgrades);
+#define STATNODE(mode, name, var, descr) \
+	SYSCTL_ULONG(_vfs_cache, OID_AUTO, name, mode, var, 0, descr);
+STATNODE(CTLFLAG_RD, numneg, &numneg, "number of negative cache entries allocated");
+STATNODE(CTLFLAG_RD, numcache, &numcache, "number of cache entries allocated");
+static u_long numcalls; STATNODE(CTLFLAG_RD, numcalls, &numcalls, "# cache lookups");
+static u_long dothits; STATNODE(CTLFLAG_RD, dothits, &dothits, " # '.' hits");
+static u_long dotdothits; STATNODE(CTLFLAG_RD, dotdothits, &dotdothits, " # '..' hits");
+static u_long numchecks; STATNODE(CTLFLAG_RD, numchecks, &numchecks, "# checks in lookup");
+static u_long nummiss; STATNODE(CTLFLAG_RD, nummiss, &nummiss, "# cache miss");
+static u_long nummisszap; STATNODE(CTLFLAG_RD, nummisszap, &nummisszap, "# cache miss we dont want to cache");
+static u_long numposhits; STATNODE(CTLFLAG_RD, numposhits, &numposhits, "# cache hits (positive)");
+static u_long numposzaps; STATNODE(CTLFLAG_RD, numposzaps, &numposzaps, "# cache hits (positive) we dont want to cache");
+static u_long numneghits; STATNODE(CTLFLAG_RD, numneghits, &numneghits, "# cache hits (negative)");
+static u_long numnegzaps; STATNODE(CTLFLAG_RD, numnegzaps, &numnegzaps, "# cache hits (negative) we dont want to cache");
+static u_long numupgrades; STATNODE(CTLFLAG_RD, numupgrades, &numupgrades, "# update the cache after lookup (write lock + retry)");
 
 SYSCTL_OPAQUE(_vfs_cache, OID_AUTO, nchstats, CTLFLAG_RD | CTLFLAG_MPSAFE,
 	&nchstats, sizeof(nchstats), "LU", "VFS cache effectiveness statistics");
@@ -964,20 +964,20 @@
  */
 
 #undef STATNODE
-#define STATNODE(name)							\
+#define STATNODE(name, descr)						\
 	static u_int name;						\
-	SYSCTL_UINT(_vfs_cache, OID_AUTO, name, CTLFLAG_RD, &name, 0, "")
+	SYSCTL_UINT(_vfs_cache, OID_AUTO, name, CTLFLAG_RD, &name, 0, descr)
 
 static int disablefullpath;
 SYSCTL_INT(_debug, OID_AUTO, disablefullpath, CTLFLAG_RW, &disablefullpath, 0,
 	"Disable the vn_fullpath function");
 
 /* These count for kern___getcwd(), too. */
-STATNODE(numfullpathcalls);
-STATNODE(numfullpathfail1);
-STATNODE(numfullpathfail2);
-STATNODE(numfullpathfail4);
-STATNODE(numfullpathfound);
+STATNODE(numfullpathcalls, "# fullpath search calls");
+STATNODE(numfullpathfail1, "# fullpath search error (ENOTDIR)");
+STATNODE(numfullpathfail2, "# fullpath search error (ENOENT)");
+STATNODE(numfullpathfail4, "# fullpath search error (ENOMEM)");
+STATNODE(numfullpathfound, "# fullpath search found");
 
 /*
  * Retrieve the full filesystem path that correspond to a vnode from the name


>Release-Note:
>Audit-Trail:
>Unformatted:

Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201007171102.o6HB2pR3045403>

Header And Logo

Peripheral Links

Site Navigation

Header And Logo

Peripheral Links

Search

Site Navigation