Improve init/Kconfig help descriptions [PATCH 0/9]

Improve init/Kconfig help descriptions [PATCH 0/9]

[Nick Andrew]

Here is a series of 9 patches to init/Kconfig intended to improve the
usefulness and consistency of the help descriptions. The patches are
against linux-2.6.24.2.

Rationale:

Even though I've been using Unix for 20+ years, I find it sometimes
daunting to configure a linux kernel. The help descriptions supplied
sometimes help, and sometimes they do not.


The problems I can see with the supplied help descriptions fall into
these areas:

  - Uses arcane terminology which only kernel developers can understand

  - Inconsistently describes safe response (if unsure, ...)

  - References out-of-date external resources (404 error)

  - Description has not kept pace with recent kernel changes or standards

  - Poor grammar or layout.


My approach to improving the descriptions is to go through each option
checking the correctness of the description, validating any references
it makes, finding inconsistency with the rest of the kernel config,
and trying to improve the usefulness of the explanation. I want to
end up with:

  1 - Single sentence summary of what the option does

  2 - Explain terminology or situation if necessary and possible, linking
  to validated information sources (Documentation directory, manpages,
  scripts, URLs, Wikipedia)

  3 - Suggest safe answer for people who just don't know what to do.

The patches are in 9 parts because I wouldn't want to overwhelm any
reviewers, and also because I might have got some of them wrong. I
learned some cool things while researching these kernel options, like
what POSIX message queues are, and about the SLAB allocator, but my
grasp of cgroups and cpusets is tenuous at best. Here's a list of
the patches and the affected config options:

Patch 1
	EXPERIMENTAL
	LOCALVERSION
	LOCALVERSION_AUTO
	SWAP
	SYSVIPC
	POSIX_MQUEUE
	BSD_PROCESS_ACCT
	BSD_PROCESS_ACCT_V3

Patch 2
	TASKSTATS
	TASK_DELAY_ACCT
	TASK_XACCT
	TASK_IO_ACCOUNTING

Patch 3
	USER_NS
	PID_NS

Patch 4
	AUDIT
	AUDITSYSCALL

Patch 5
	IKCONFIG
	IKCONFIG_PROC
	LOG_BUF_SHIFT
	SYSFS_DEPRECATED
	RELAY
	BLK_DEV_INITRD

Patch 6
	CGROUPS
	CGROUP_DEBUG
	CPUSETS
	FAIR_GROUP_SCHED
	FAIR_CGROUP_SCHED
	CGROUP_CPUACCT
	PROC_PID_CPUSET

Patch 7
	EMBEDDED
	SYSCTL_SYSCALL
	KALLSYMS
	KALLSYMS_ALL
	KALLSYMS_EXTRA_PASS
	HOTPLUG
	PRINTK
	BUG
	ELF_CORE
	BASE_FULL
	FUTEX
	EPOLL
	SIGNALFD
	TIMERFD
	EVENTFD

Patch 8
	SLUB_DEBUG
	SLAB
	SLUB
	SLOB

Patch 9
	MODULES
	MODULE_UNLOAD
	MODULE_FORCE_UNLOAD
	MODVERSIONS
	MODULE_SRCVERSION_ALL
	KMOD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
-- 
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7

Improve init/Kconfig help descriptions [PATCH 1/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 1
> 	EXPERIMENTAL
> 	LOCALVERSION
> 	LOCALVERSION_AUTO
> 	SWAP
> 	SYSVIPC
> 	POSIX_MQUEUE
> 	BSD_PROCESS_ACCT
> 	BSD_PROCESS_ACCT_V3

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
 
--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -12,33 +12,45 @@ menu "General setup"
 config EXPERIMENTAL
 	bool "Prompt for development and/or incomplete code/drivers"
 	---help---
-	  Some of the various things that Linux supports (such as network
-	  drivers, file systems, network protocols, etc.) can be in a state
-	  of development where the functionality, stability, or the level of
-	  testing is not yet high enough for general use. This is usually
-	  known as the "alpha-test" phase among developers. If a feature is
-	  currently in alpha-test, then the developers usually discourage
-	  uninformed widespread use of this feature by the general public to
-	  avoid "Why doesn't this work?" type mail messages. However, active
-	  testing and use of these systems is welcomed. Just be aware that it
-	  may not meet the normal level of reliability or it may fail to work
-	  in some special cases. Detailed bug reports from people familiar
-	  with the kernel internals are usually welcomed by the developers
-	  (before submitting bug reports, please read the documents
-	  <file:README>, <file:MAINTAINERS>, <file:REPORTING-BUGS>,
-	  <file:Documentation/BUG-HUNTING>, and
-	  <file:Documentation/oops-tracing.txt> in the kernel source).
+	  This option enables you to choose kernel configuration
+	  options labeled as EXPERIMENTAL.
+
+	  Some of the various things that Linux supports (such as
+	  network drivers, file systems, network protocols, etc.) can
+	  be in a state of development where the functionality,
+	  stability, or the level of testing is not yet high enough
+	  for general use. This is usually known as the "alpha-test"
+	  phase among developers.
+
+	  If a feature is currently in alpha-test, then the
+	  developers usually discourage uninformed widespread use of
+	  this feature by the general public to avoid "Why doesn't
+	  this work?" type email messages. However, active testing
+	  and use of these systems is welcomed. Just be aware that
+	  it may not meet the normal level of reliability or it
+	  may fail to work in some special cases.
+
+	  Detailed bug reports from people familiar with
+	  the kernel internals are usually welcomed by the
+	  developers. Before submitting bug reports, please
+	  read the documents <file:README>, <file:MAINTAINERS>,
+	  <file:REPORTING-BUGS>, <file:Documentation/BUG-HUNTING>,
+	  and <file:Documentation/oops-tracing.txt> in the kernel
+	  source.
 
 	  This option will also make obsoleted drivers available. These are
 	  drivers that have been replaced by something else, and/or are
 	  scheduled to be removed in a future kernel release.
 
-	  Unless you intend to help test and develop a feature or driver that
-	  falls into this category, or you have a situation that requires
-	  using these features, you should probably say N here, which will
-	  cause the configurator to present you with fewer choices. If
-	  you say Y here, you will be offered the choice of using features or
-	  drivers that are currently considered to be in the alpha-test phase.
+	  Unless you intend to help test and develop a feature or driver
+	  that falls into this category, or you have a situation that
+	  requires using these features, you should probably say N here,
+	  which will cause the configurator to present you with fewer
+	  choices. If you say Y here, you will be offered the choice of
+	  using features or drivers that are currently considered to be
+	  in the alpha-test phase.
+
+	  If unsure, say N.
 
 config BROKEN
 	bool
@@ -66,11 +78,18 @@ config LOCALVERSION
 	string "Local version - append to kernel release"
 	help
 	  Append an extra string to the end of your kernel version.
-	  This will show up when you type uname, for example.
-	  The string you set here will be appended after the contents of
-	  any files with a filename matching localversion* in your
-	  object and source tree, in that order.  Your total string can
-	  be a maximum of 64 characters.
+	  This will show up when you type "uname -r", for example.
+
+	  If you have any files with names matching "localversion*"
+	  in your object or source trees, then the contents of these
+	  files will be appended to your kernel version name.
+
+	  The strings are appended from the object tree files and
+	  then the source tree files, then any string specified
+	  by CONFIG_LOCALVERSION_AUTO below, and finally the value
+	  specified here.
+
+	  The maximum length of a kernel version name is 64 characters.
 
 config LOCALVERSION_AUTO
 	bool "Automatically append version information to the version string"
@@ -85,38 +104,47 @@ config LOCALVERSION_AUTO
 	  appended after any matching localversion* files, and after the value
 	  set in CONFIG_LOCALVERSION.
 
-	  (The actual string used here is the first eight characters produced
+	  The actual string used here is the first eight characters produced
 	  by running the command:
 
 	    $ git rev-parse --verify HEAD
 
-	  which is done within the script "scripts/setlocalversion".)
+	  which is done within the script "scripts/setlocalversion".
 
 config SWAP
 	bool "Support for paging of anonymous memory (swap)"
 	depends on MMU && BLOCK
 	default y
 	help
-	  This option allows you to choose whether you want to have support
-	  for so called swap devices or swap files in your kernel that are
-	  used to provide more virtual memory than the actual RAM present
-	  in your computer.  If unsure say Y.
+	  This option allows you to choose whether you want to have
+	  support for swap devices or swap files in your kernel.
+
+	  Swap is used to provide more virtual memory than the
+	  actual RAM present in your computer. This can improve
+	  performance by moving less frequently used blocks of
+	  memory onto disk, which frees it up for improved disk
+	  caching or active processes.
+
+	  If unsure, say Y.
 
 config SYSVIPC
 	bool "System V IPC"
 	---help---
-	  Inter Process Communication is a suite of library functions and
+	  Inter-Process Communication is a suite of library functions and
 	  system calls which let processes (running programs) synchronize and
 	  exchange information. It is generally considered to be a good thing,
-	  and some programs won't run unless you say Y here. In particular, if
-	  you want to run the DOS emulator dosemu under Linux (read the
-	  DOSEMU-HOWTO, available from <http://www.tldp.org/docs.html#howto>),
-	  you'll need to say Y here.
+	  and some programs won't run without it.
+
+	  In particular, if you want to run the DOS emulator dosemu
+	  under Linux, you'll need to say Y here. You can find out
+	  more about dosemu at <http://dosemu.sourceforge.net/>
 
 	  You can find documentation about IPC with "info ipc" and also in
 	  section 6.4 of the Linux Programmer's Guide, available from
 	  <http://www.tldp.org/guides.html>.
 
+	  If unsure, say Y.
+
 config SYSVIPC_SYSCTL
 	bool
 	depends on SYSVIPC
@@ -127,42 +155,69 @@ config POSIX_MQUEUE
 	bool "POSIX Message Queues"
 	depends on NET && EXPERIMENTAL
 	---help---
-	  POSIX variant of message queues is a part of IPC. In POSIX message
-	  queues every message has a priority which decides about succession
-	  of receiving it by a process. If you want to compile and run
-	  programs written e.g. for Solaris with use of its POSIX message
-	  queues (functions mq_*) say Y here.
-
-	  POSIX message queues are visible as a filesystem called 'mqueue'
-	  and can be mounted somewhere if you want to do filesystem
-	  operations on message queues.
+	  POSIX Message Queues is a type of Inter-Process Communication
+	  (IPC). It provides similar functionality to System V message
+	  queues, with a different Application Programming Interface (API).
+
+	  In POSIX Message Queues, every message has a priority which
+	  determines the order in which each message is delivered to a
+	  receiving process. See mq_overview(7) for details of the
+	  API (functions mq_*).
+
+	  When POSIX Message Queues are enabled, a directory appears
+	  called /proc/sys/fs/mqueue which can be used to tune kernel
+	  parameters. See mq_overview(7) for details.
+
+	  POSIX Message Queues can also be mounted as a filesystem
+	  called 'mqueue', for example: "mount -t mqueue none /mqueue".
 
 	  If unsure, say Y.
 
 config BSD_PROCESS_ACCT
 	bool "BSD Process Accounting"
 	help
-	  If you say Y here, a user level program will be able to instruct the
-	  kernel (via a special system call) to write process accounting
-	  information to a file: whenever a process exits, information about
-	  that process will be appended to the file by the kernel.  The
-	  information includes things such as creation time, owning user,
-	  command name, memory usage, controlling terminal etc. (the complete
-	  list is in the struct acct in <file:include/linux/acct.h>).  It is
-	  up to the user level program to do useful things with this
-	  information.  This is generally a good idea, so say Y.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Whenever a process exits, information about that process
+	  will be appended to the file. This includes things such as
+	  creation time, owning user, command name, memory usage,
+	  controlling terminal, etc.
+
+	  See sa(1), accton(8) and acct(2) for more details, also
+	  <file:include/linux/acct.h> (struct acct) for the complete
+	  list of stored data.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config BSD_PROCESS_ACCT_V3
 	bool "BSD Process Accounting version 3 file format"
 	depends on BSD_PROCESS_ACCT
 	default n
 	help
-	  If you say Y here, the process accounting information is written
-	  in a new file format that also logs the process IDs of each
-	  process and it's parent. Note that this file format is incompatible
-	  with previous v0/v1/v2 file formats, so you will need updated tools
-	  for processing it. A preliminary version of these tools is available
-	  at <http://www.physik3.uni-rostock.de/tim/kernel/utils/acct/>.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Version 3 is a new file format that also logs the process
+	  ID and process parent ID.
+
+	  Note that this file format is incompatible with previous
+	  v0/v1/v2 file formats, so you will need updated tools
+	  for processing it. One such tool is "bootchart", and
+	  the GNU "acct" package should be able to read the v3
+	  file format too.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config TASKSTATS
 	bool "Export task/process statistics through netlink (EXPERIMENTAL)"

Re: Improve init/Kconfig help descriptions [PATCH 2/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 2
> 	TASKSTATS
> 	TASK_DELAY_ACCT
> 	TASK_XACCT
> 	TASK_IO_ACCOUNTING

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>

--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -169,42 +169,52 @@ config TASKSTATS
 	depends on NET
 	default n
 	help
-	  Export selected statistics for tasks/processes through the
-	  generic netlink interface. Unlike BSD process accounting, the
-	  statistics are available during the lifetime of tasks/processes as
-	  responses to commands. Like BSD accounting, they are sent to user
-	  space on task exit.
+	  Taskstats is a netlink-based interface for sending per-task
+	  and per-process statistics from the kernel to userspace.
 
-	  Say N if unsure.
+	  Unlike BSD process accounting, the statistics are available
+	  during the lifetime of tasks/processes as responses to
+	  commands. Like BSD accounting, they are sent to user space on
+	  task exit.
+
+	  Netlink is a type of network socket used to transfer data
+	  between the kernel and user space. For more information on
+	  Netlink see <http://qos.ittc.ku.edu/netlink/html/index.html>
+
+	  See <file:Documentation/accounting/taskstats.txt> for more
+	  information on taskstats.
+
+	  If unsure, say N.
 
 config TASK_DELAY_ACCT
 	bool "Enable per-task delay accounting (EXPERIMENTAL)"
 	depends on TASKSTATS
 	help
-	  Collect information on time spent by a task waiting for system
-	  resources like cpu, synchronous block I/O completion and swapping
-	  in pages. Such statistics can help in setting a task's priorities
-	  relative to other tasks for cpu, io, rss limits etc.
+	  Also collect information on time spent by a task waiting for
+	  system resources like CPU, synchronous block I/O completion and
+	  swapping in pages. Such statistics can help in setting a task's
+	  priorities relative to other tasks for CPU, I/O, RSS limits etc.
 
-	  Say N if unsure.
+	  If unsure, say N.
 
 config TASK_XACCT
 	bool "Enable extended accounting over taskstats (EXPERIMENTAL)"
 	depends on TASKSTATS
 	help
-	  Collect extended task accounting data and send the data
-	  to userland for processing over the taskstats interface.
+	  Also collect extended task accounting data and send
+	  the data to userland for processing over the taskstats
+	  interface.
 
-	  Say N if unsure.
+	  If unsure, say N.
 
 config TASK_IO_ACCOUNTING
 	bool "Enable per-task storage I/O accounting (EXPERIMENTAL)"
 	depends on TASK_XACCT
 	help
-	  Collect information on the number of bytes of storage I/O which this
-	  task has caused.
+	  Also collect information on the number of bytes of storage
+	  I/O which this task has caused.
 
-	  Say N if unsure.
+	  If unsure, say N.
 
 config USER_NS
 	bool "User Namespaces (EXPERIMENTAL)"

Improve init/Kconfig help descriptions [PATCH 3/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 3
> 	USER_NS
> 	PID_NS

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>

--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -211,21 +211,25 @@ config USER_NS
 	default n
 	depends on EXPERIMENTAL
 	help
-	  Support user namespaces.  This allows containers, i.e.
-	  vservers, to use user namespaces to provide different
-	  user info for different servers.  If unsure, say N.
+	  Enable support for user namespaces.
+
+	  This allows containers (i.e. vservers) to use user namespaces
+	  to provide different user info for different servers.
+
+	  If unsure, say N.
 
 config PID_NS
 	bool "PID Namespaces (EXPERIMENTAL)"
 	default n
 	depends on EXPERIMENTAL
 	help
-	  Suport process id namespaces.  This allows having multiple
-	  process with the same pid as long as they are in different
-	  pid namespaces.  This is a building block of containers.
+	  Enable support for process id namespaces.
 
-	  Unless you want to work with an experimental feature
-	  say N here.
+	  This allows having multiple processes with the same PID as
+	  long as they are in different PID namespaces.  This is used
+	  by containers (i.e. vservers).
+
+	  If unsure, say N.
 
 config AUDIT
 	bool "Auditing support"

Re: Improve init/Kconfig help descriptions [PATCH 3/9]

[Pavel Emelyanov]

Nick Andrew wrote:
> On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
>> Here is a series of 9 patches to init/Kconfig intended to improve the
>> usefulness and consistency of the help descriptions. The patches are
>> against linux-2.6.24.2.
>> [...]
>> Patch 3
>> 	USER_NS
>> 	PID_NS

What about UTS_NS, IPC_NS and NET_NS? 
Their descriptions can be improved in the same way :)

> Changelog:
> 
> Improve usefulness and consistency of kernel configuration help messages.
> 
> Signed-off-by: Nick Andrew <nick@nick-andrew.net>
> 
> --- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
> +++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
> @@ -211,21 +211,25 @@ config USER_NS
>  	default n
>  	depends on EXPERIMENTAL
>  	help
> -	  Support user namespaces.  This allows containers, i.e.
> -	  vservers, to use user namespaces to provide different
> -	  user info for different servers.  If unsure, say N.
> +	  Enable support for user namespaces.
> +
> +	  This allows containers (i.e. vservers) to use user namespaces
> +	  to provide different user info for different servers.
> +
> +	  If unsure, say N.
>  
>  config PID_NS
>  	bool "PID Namespaces (EXPERIMENTAL)"
>  	default n
>  	depends on EXPERIMENTAL
>  	help
> -	  Suport process id namespaces.  This allows having multiple
> -	  process with the same pid as long as they are in different
> -	  pid namespaces.  This is a building block of containers.
> +	  Enable support for process id namespaces.
>  
> -	  Unless you want to work with an experimental feature
> -	  say N here.
> +	  This allows having multiple processes with the same PID as
> +	  long as they are in different PID namespaces.  This is used
> +	  by containers (i.e. vservers).
> +
> +	  If unsure, say N.
>  
>  config AUDIT
>  	bool "Auditing support"
> --
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
> 

Re: Improve init/Kconfig help descriptions [PATCH 3/9]

[Nick Andrew]

On Tue, Feb 19, 2008 at 05:42:07PM +0300, Pavel Emelyanov wrote:
> Nick Andrew wrote:
> > On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> >> Here is a series of 9 patches to init/Kconfig intended to improve the
> >> usefulness and consistency of the help descriptions. The patches are
> >> against linux-2.6.24.2.
> >> [...]
> >> Patch 3
> >> 	USER_NS
> >> 	PID_NS
> 
> What about UTS_NS, IPC_NS and NET_NS? 
> Their descriptions can be improved in the same way :)

So far I have edited only init/Kconfig, that's what these 9
patches are for. Next I'll do block/Kconfig. Eventually I expect
to get to net/Kconfig which is where NET_NS is configured,
but I don't know where UTS_NS and IPC_NS come from in 2.6.24.2.

I expect I'll have to start patching against a git tree soon,
to be sure to see the latest code. I assume this should be
Linus' tree?

Is there any actual documentation on user namespaces and friends?
I think I grasp the pid namespaces concept; I am having a little
difficulty visualising what function user namespaces performs.
"provide different user info" isn't a very useful description and
I'd fix it if I understood what it is supposed to mean.

To make a guess at it, how about:

   Enable support for user namespaces.

   This is a function used by container-based virtualisation systems
   (e.g. vservers). User namespaces ensures that processes with the
   same uid which are in different containers are isolated from each other.

   Answer Y if you require container-based virtualisation like
   vservers. If unsure, say N.

Nick.
-- 
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7

Re: Improve init/Kconfig help descriptions [PATCH 3/9]

[Pavel Emelyanov]

Nick Andrew wrote:
> On Tue, Feb 19, 2008 at 05:42:07PM +0300, Pavel Emelyanov wrote:
>> Nick Andrew wrote:
>>> On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
>>>> Here is a series of 9 patches to init/Kconfig intended to improve the
>>>> usefulness and consistency of the help descriptions. The patches are
>>>> against linux-2.6.24.2.
>>>> [...]
>>>> Patch 3
>>>> 	USER_NS
>>>> 	PID_NS
>> What about UTS_NS, IPC_NS and NET_NS? 
>> Their descriptions can be improved in the same way :)
> 
> So far I have edited only init/Kconfig, that's what these 9
> patches are for. Next I'll do block/Kconfig. Eventually I expect
> to get to net/Kconfig which is where NET_NS is configured,
> but I don't know where UTS_NS and IPC_NS come from in 2.6.24.2.
> 
> I expect I'll have to start patching against a git tree soon,
> to be sure to see the latest code. I assume this should be
> Linus' tree?

Both UTS_NS and IPC_NS are in init/Kconfg. At least they are
in 2.6.25-rc2 :)

> Is there any actual documentation on user namespaces and friends?

Hardly :(

> I think I grasp the pid namespaces concept; I am having a little
> difficulty visualising what function user namespaces performs.
> "provide different user info" isn't a very useful description and
> I'd fix it if I understood what it is supposed to mean.

The pid namespaces are described here: http://lwn.net/Articles/259217/

> To make a guess at it, how about:
> 
>    Enable support for user namespaces.
> 
>    This is a function used by container-based virtualisation systems
>    (e.g. vservers). User namespaces ensures that processes with the
>    same uid which are in different containers are isolated from each other.
> 
>    Answer Y if you require container-based virtualisation like
>    vservers. If unsure, say N.

You'd better talk to Serge Hallyn (in Cc) about them. He had some
thoughts on how to complete them :)

> Nick.

Re: Improve init/Kconfig help descriptions [PATCH 3/9]

[Serge E. Hallyn]

Quoting Pavel Emelyanov (xemul@openvz.org):
> Nick Andrew wrote:
> > On Tue, Feb 19, 2008 at 05:42:07PM +0300, Pavel Emelyanov wrote:
> >> Nick Andrew wrote:
> >>> On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> >>>> Here is a series of 9 patches to init/Kconfig intended to improve the
> >>>> usefulness and consistency of the help descriptions. The patches are
> >>>> against linux-2.6.24.2.
> >>>> [...]
> >>>> Patch 3
> >>>> 	USER_NS
> >>>> 	PID_NS
> >> What about UTS_NS, IPC_NS and NET_NS? 
> >> Their descriptions can be improved in the same way :)
> > 
> > So far I have edited only init/Kconfig, that's what these 9
> > patches are for. Next I'll do block/Kconfig. Eventually I expect
> > to get to net/Kconfig which is where NET_NS is configured,
> > but I don't know where UTS_NS and IPC_NS come from in 2.6.24.2.
> > 
> > I expect I'll have to start patching against a git tree soon,
> > to be sure to see the latest code. I assume this should be
> > Linus' tree?
> 
> Both UTS_NS and IPC_NS are in init/Kconfg. At least they are
> in 2.6.25-rc2 :)
> 
> > Is there any actual documentation on user namespaces and friends?
> 
> Hardly :(
> 
> > I think I grasp the pid namespaces concept; I am having a little
> > difficulty visualising what function user namespaces performs.
> > "provide different user info" isn't a very useful description and
> > I'd fix it if I understood what it is supposed to mean.
> 
> The pid namespaces are described here: http://lwn.net/Articles/259217/
> 
> > To make a guess at it, how about:
> > 
> >    Enable support for user namespaces.
> > 
> >    This is a function used by container-based virtualisation systems
> >    (e.g. vservers). User namespaces ensures that processes with the
> >    same uid which are in different containers are isolated from each other.
> > 
> >    Answer Y if you require container-based virtualisation like
> >    vservers. If unsure, say N.
> 
> You'd better talk to Serge Hallyn (in Cc) about them. He had some
> thoughts on how to complete them :)

That describes the final intent for user namespaces.  Currently all they
do is provide for separate accounting for the same uid in different user
namespaces.  To provide actual isolation/security, you would currently
want to use an LSM.  I'm currently playing with some selinux policy
infrastructure to make that easier.

So as for the description, for now it should probably read something
like:

    Enable experimental support for user namespaces.
 
    This is a function used by container-based virtualisation systems
    (e.g. vservers). User namespaces are intended to ensure that
    processes with the same uid which are in different containers are
    isolated from each other.

    Currently user namespaces provide separate accounting, while
    isolation must be provided using SELinux or a custom security
    module.
 
    Answer Y if you require container-based virtualisation like
    vservers. If unsure, say N.

> 
> > Nick.

thanks,
-serge

Re: Improve init/Kconfig help descriptions [PATCH 3/9]

[Randy Dunlap]

On Tue, 19 Feb 2008 18:16:53 +0300 Pavel Emelyanov wrote:

> Nick Andrew wrote:
> > On Tue, Feb 19, 2008 at 05:42:07PM +0300, Pavel Emelyanov wrote:
> >> Nick Andrew wrote:
> >>> On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> >>>> Here is a series of 9 patches to init/Kconfig intended to improve the
> >>>> usefulness and consistency of the help descriptions. The patches are
> >>>> against linux-2.6.24.2.
> >>>> [...]
> >>>> Patch 3
> >>>> 	USER_NS
> >>>> 	PID_NS
> >> What about UTS_NS, IPC_NS and NET_NS? 
> >> Their descriptions can be improved in the same way :)
> > 
> > So far I have edited only init/Kconfig, that's what these 9
> > patches are for. Next I'll do block/Kconfig. Eventually I expect
> > to get to net/Kconfig which is where NET_NS is configured,
> > but I don't know where UTS_NS and IPC_NS come from in 2.6.24.2.
> > 
> > I expect I'll have to start patching against a git tree soon,
> > to be sure to see the latest code. I assume this should be
> > Linus' tree?
> 
> Both UTS_NS and IPC_NS are in init/Kconfg. At least they are
> in 2.6.25-rc2 :)

Yes, these patches should be made against the latest development
tree, not the stable tree.


---
~Randy

Re: Improve init/Kconfig help descriptions [PATCH 3/9]

[Nick Andrew]

On Tue, Feb 19, 2008 at 08:44:20AM -0800, Randy Dunlap wrote:
> Yes, these patches should be made against the latest development
> tree, not the stable tree.

Thanks for the comments and advice, I'll make a new set of patches
against Linus' tree and post them in when they are ready.

Nick.
-- 
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7

[PATCH 2.6.25-rc2 3/9] config: Improve init/Kconfig help descriptions - namespaces

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - NAMESPACES
  - UTS_NS
  - IPC_NS
  - USER_NS
  - PID_NS

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Here's try #2 at the 3rd patch in the series, for namespace
descriptions. Patching against Linus' git tree now, and trying
to comply with the standards for submitting patches. Each of
the UTS/IPC/USER/PID descriptions is subtly different, but I
hope they all are clear and accurate.


--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-20 22:55:41.000000000 +1100
@@ -414,31 +414,71 @@
 	bool "Namespaces support" if EMBEDDED
 	default !EMBEDDED
 	help
-	  Provides the way to make tasks work with different objects using
-	  the same id. For example same IPC id may refer to different objects
-	  or same user id or pid may refer to different tasks when used in
-	  different namespaces.
+	  Select various namespace options.
+
+	  Namespaces allow different kernel objects (such as processes
+	  or sockets) to have the same ID in different namespaces.
+	  Identifiers like process IDs, which historically were globally
+	  unique, will now be unique only within each PID namespace.
+	  Each task can refer only to PIDs within the same namespace
+	  as the task itself.
+
+	  Namespaces are used by container systems (i.e. vservers)
+	  to provide isolation between the containers.
+
+	  This option does not affect any kernel code directly; it merely
+	  allows you to select namespace options below.
+
+	  Answer Y if you will be using a container system, and you
+	  will probably want to enable all the namespace options
+	  below.
 
 config UTS_NS
 	bool "UTS namespace"
 	depends on NAMESPACES
 	help
-	  In this namespace tasks see different info provided with the
-	  uname() system call
+	  Enable support for multiple UTS system attributes.
+
+	  Each UTS namespace provides an individual view of the
+	  information returned by the uname() system call including
+	  hostname, kernel version and domain name.
+
+	  This is used by container systems (i.e. vservers) so that
+	  each container has its own hostname and other attributes.
+	  Tasks in the container are placed in the UTS namespace
+	  corresponding to the container.
+
+	  Answer Y if you will be using a container system.
 
 config IPC_NS
 	bool "IPC namespace"
 	depends on NAMESPACES && SYSVIPC
 	help
-	  In this namespace tasks work with IPC ids which correspond to
-	  different IPC objects in different namespaces
+	  Enable support for namespace-specific IPC IDs.
+
+	  IPC IDs will be unique only within each IPC namespace.
+
+	  This is used by container systems (i.e. vservers).
+	  Tasks in the container are placed in the IPC namespace
+	  corresponding to the container.
+
+	  Answer Y if you will be using a container system.
 
 config USER_NS
 	bool "User namespace (EXPERIMENTAL)"
 	depends on NAMESPACES && EXPERIMENTAL
 	help
-	  This allows containers, i.e. vservers, to use user namespaces
-	  to provide different user info for different servers.
+	  Enable experimental support for user namespaces.
+
+	  This is a function used by container-based virtualisation systems
+	  (e.g. vservers). User namespaces are intended to ensure that
+	  processes with the same uid which are in different containers are
+	  isolated from each other.
+
+	  Currently user namespaces provide separate accounting, while
+	  isolation must be provided using SELinux or a custom security
+	  module.
+
 	  If unsure, say N.
 
 config PID_NS
@@ -446,12 +486,20 @@
 	default n
 	depends on NAMESPACES && EXPERIMENTAL
 	help
-	  Suport process id namespaces.  This allows having multiple
-	  process with the same pid as long as they are in different
-	  pid namespaces.  This is a building block of containers.
+	  Enable experimental support for hierarchical process id namespaces.
 
-	  Unless you want to work with an experimental feature
-	  say N here.
+	  Process IDs will be unique only within each PID namespace.
+	  This allows multiple processes to have the same PID
+	  so long as they are in different PID namespaces. Furthermore,
+	  each process will have a distinct PID in each namespace
+	  the process is in.
+
+	  This is used by container systems (i.e. vservers).
+	  Tasks in the container are placed in the PID namespace
+	  corresponding to the container, and can only see or
+	  affect processes in the same PID namespace.
+
+	  If unsure, say N.
 
 config BLK_DEV_INITRD
 	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"

Re: [PATCH 2.6.25-rc2 3/9] config: Improve init/Kconfig help descriptions - namespaces

[Pavel Emelyanov]

Nick Andrew wrote:
> Rewrite the help descriptions for clarity, accuracy and consistency.
> 
> Kernel config options affected:
> 
>   - NAMESPACES
>   - UTS_NS
>   - IPC_NS
>   - USER_NS
>   - PID_NS
> 
> Signed-off-by: Nick Andrew <nick@nick-andrew.net>
> ---
> Here's try #2 at the 3rd patch in the series, for namespace
> descriptions. Patching against Linus' git tree now, and trying
> to comply with the standards for submitting patches. Each of
> the UTS/IPC/USER/PID descriptions is subtly different, but I
> hope they all are clear and accurate.
> 
> 
> --- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
> +++ b/init/Kconfig	2008-02-20 22:55:41.000000000 +1100
> @@ -414,31 +414,71 @@
>  	bool "Namespaces support" if EMBEDDED
>  	default !EMBEDDED
>  	help
> -	  Provides the way to make tasks work with different objects using
> -	  the same id. For example same IPC id may refer to different objects
> -	  or same user id or pid may refer to different tasks when used in
> -	  different namespaces.
> +	  Select various namespace options.
> +
> +	  Namespaces allow different kernel objects (such as processes
> +	  or sockets) to have the same ID in different namespaces.
> +	  Identifiers like process IDs, which historically were globally
> +	  unique, will now be unique only within each PID namespace.
> +	  Each task can refer only to PIDs within the same namespace
> +	  as the task itself.
> +
> +	  Namespaces are used by container systems (i.e. vservers)
> +	  to provide isolation between the containers.
> +
> +	  This option does not affect any kernel code directly; it merely
> +	  allows you to select namespace options below.
> +
> +	  Answer Y if you will be using a container system, and you
> +	  will probably want to enable all the namespace options
> +	  below.
>  
>  config UTS_NS
>  	bool "UTS namespace"
>  	depends on NAMESPACES
>  	help
> -	  In this namespace tasks see different info provided with the
> -	  uname() system call
> +	  Enable support for multiple UTS system attributes.
> +
> +	  Each UTS namespace provides an individual view of the
> +	  information returned by the uname() system call including
> +	  hostname, kernel version and domain name.
> +
> +	  This is used by container systems (i.e. vservers) so that
> +	  each container has its own hostname and other attributes.
> +	  Tasks in the container are placed in the UTS namespace
> +	  corresponding to the container.
> +
> +	  Answer Y if you will be using a container system.
>  
>  config IPC_NS
>  	bool "IPC namespace"
>  	depends on NAMESPACES && SYSVIPC
>  	help
> -	  In this namespace tasks work with IPC ids which correspond to
> -	  different IPC objects in different namespaces
> +	  Enable support for namespace-specific IPC IDs.
> +
> +	  IPC IDs will be unique only within each IPC namespace.
> +
> +	  This is used by container systems (i.e. vservers).
> +	  Tasks in the container are placed in the IPC namespace
> +	  corresponding to the container.
> +
> +	  Answer Y if you will be using a container system.
>  
>  config USER_NS
>  	bool "User namespace (EXPERIMENTAL)"
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  This allows containers, i.e. vservers, to use user namespaces
> -	  to provide different user info for different servers.
> +	  Enable experimental support for user namespaces.
> +
> +	  This is a function used by container-based virtualisation systems
> +	  (e.g. vservers). User namespaces are intended to ensure that
> +	  processes with the same uid which are in different containers are
> +	  isolated from each other.
> +
> +	  Currently user namespaces provide separate accounting, while
> +	  isolation must be provided using SELinux or a custom security
> +	  module.
> +
>  	  If unsure, say N.
>  
>  config PID_NS
> @@ -446,12 +486,20 @@
>  	default n
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  Suport process id namespaces.  This allows having multiple
> -	  process with the same pid as long as they are in different
> -	  pid namespaces.  This is a building block of containers.
> +	  Enable experimental support for hierarchical process id namespaces.
>  
> -	  Unless you want to work with an experimental feature
> -	  say N here.
> +	  Process IDs will be unique only within each PID namespace.
> +	  This allows multiple processes to have the same PID
> +	  so long as they are in different PID namespaces. Furthermore,
> +	  each process will have a distinct PID in each namespace
> +	  the process is in.
> +
> +	  This is used by container systems (i.e. vservers).
> +	  Tasks in the container are placed in the PID namespace
> +	  corresponding to the container, and can only see or
> +	  affect processes in the same PID namespace.

same of one of child namespaces. In other words when you create
a new pid namespace, you still see the tasks from this new one,
but the tasks from this one, doesn't see yours :)

> +
> +	  If unsure, say N.
>  
>  config BLK_DEV_INITRD
>  	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"
> 

Re: [PATCH 2.6.25-rc2 3/9] config: Improve init/Kconfig help descriptions - namespaces

[Nick Andrew]

On Wed, Feb 20, 2008 at 03:23:05PM +0300, Pavel Emelyanov wrote:
> > +	  This is used by container systems (i.e. vservers).
> > +	  Tasks in the container are placed in the PID namespace
> > +	  corresponding to the container, and can only see or
> > +	  affect processes in the same PID namespace.
> 
> same of one of child namespaces. In other words when you create
> a new pid namespace, you still see the tasks from this new one,
> but the tasks from this one, doesn't see yours :)

Due to the hierarchial nature, I see. I'm still trying to grok
it. Would it be adequate to describe what a process _cannot_
do? i.e.

          This is used by container systems (i.e. vservers).
          Tasks in the container are placed in the PID namespace
          corresponding to the container, and cannot see or
          affect processes in any parent PID namespaces.

Or maybe I should say both what it cannot do and what it can,
so readers don't have to use their imagination much :-)

Let's see if I understand how it works with an example. Say we've
got a hierarchy of PID namespaces ... pidA/pidB/pidC and a new
process created in pidC. This new process may have pid 18925 in
pidA, 2263 in pidB and 56 in pidC?

So if there's another process running in pidC, the first process
may be signaled as pid 56, and if a process is running in pidB
it would be 2263 and not 56. Can a process running in pidB see
all processes running in pidC only with their pidB PIDs?

Now, a process A running in pidA can send a signal to a process
C running in pidC but not vice-versa. Process C cannot know
where the signal came from. Is there any kernel mechanism
which normally would provide that kind of information to
process C but which breaks when PID namespaces are used,
because there's no way to name process A from the context
of pidC ?

Nick.

Re: [PATCH 2.6.25-rc2 3/9] config: Improve init/Kconfig help descriptions - namespaces

[Pavel Emelyanov]

Nick Andrew wrote:
> On Wed, Feb 20, 2008 at 03:23:05PM +0300, Pavel Emelyanov wrote:
>>> +	  This is used by container systems (i.e. vservers).
>>> +	  Tasks in the container are placed in the PID namespace
>>> +	  corresponding to the container, and can only see or
>>> +	  affect processes in the same PID namespace.
>> same of one of child namespaces. In other words when you create
>> a new pid namespace, you still see the tasks from this new one,
>> but the tasks from this one, doesn't see yours :)
> 
> Due to the hierarchial nature, I see. I'm still trying to grok
> it. Would it be adequate to describe what a process _cannot_
> do? i.e.
> 
>           This is used by container systems (i.e. vservers).
>           Tasks in the container are placed in the PID namespace
>           corresponding to the container, and cannot see or
>           affect processes in any parent PID namespaces.

This looks better.

> Or maybe I should say both what it cannot do and what it can,
> so readers don't have to use their imagination much :-)

I think this would be redundant.

> Let's see if I understand how it works with an example. Say we've
> got a hierarchy of PID namespaces ... pidA/pidB/pidC and a new
> process created in pidC. This new process may have pid 18925 in
> pidA, 2263 in pidB and 56 in pidC?

Yes.

> So if there's another process running in pidC, the first process
> may be signaled as pid 56, and if a process is running in pidB
> it would be 2263 and not 56. Can a process running in pidB see
> all processes running in pidC only with their pidB PIDs?

Yes it can.

> Now, a process A running in pidA can send a signal to a process
> C running in pidC but not vice-versa. 

Right.

> Process C cannot know where the signal came from. 

Signal delivery is not yet finished, but this is what we
plan to do.

> Is there any kernel mechanism
> which normally would provide that kind of information to
> process C but which breaks when PID namespaces are used,
> because there's no way to name process A from the context
> of pidC ?

If the process from pidC receives a signal from pidB or pidA
then the appropriate siginfo will (ok - should :)) contain the 
SI_KERNEL code and zero pid, as if the kernel shoot this process.

> Nick.
> 

Re: [PATCH 2.6.25-rc2 3/9] config: Improve init/Kconfig help descriptions - namespaces

[serge]

Quoting Nick Andrew (nick@nick-andrew.net):
> Rewrite the help descriptions for clarity, accuracy and consistency.
> 
> Kernel config options affected:
> 
>   - NAMESPACES
>   - UTS_NS
>   - IPC_NS
>   - USER_NS
>   - PID_NS
> 
> Signed-off-by: Nick Andrew <nick@nick-andrew.net>
> ---
> Here's try #2 at the 3rd patch in the series, for namespace
> descriptions. Patching against Linus' git tree now, and trying
> to comply with the standards for submitting patches. Each of
> the UTS/IPC/USER/PID descriptions is subtly different, but I
> hope they all are clear and accurate.
> 
> 
> --- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
> +++ b/init/Kconfig	2008-02-20 22:55:41.000000000 +1100
> @@ -414,31 +414,71 @@
>  	bool "Namespaces support" if EMBEDDED
>  	default !EMBEDDED
>  	help
> -	  Provides the way to make tasks work with different objects using
> -	  the same id. For example same IPC id may refer to different objects
> -	  or same user id or pid may refer to different tasks when used in
> -	  different namespaces.
> +	  Select various namespace options.
> +
> +	  Namespaces allow different kernel objects (such as processes
> +	  or sockets) to have the same ID in different namespaces.
> +	  Identifiers like process IDs, which historically were globally
> +	  unique, will now be unique only within each PID namespace.
> +	  Each task can refer only to PIDs within the same namespace
> +	  as the task itself.
> +
> +	  Namespaces are used by container systems (i.e. vservers)
> +	  to provide isolation between the containers.
> +
> +	  This option does not affect any kernel code directly; it merely
> +	  allows you to select namespace options below.
> +
> +	  Answer Y if you will be using a container system, and you
> +	  will probably want to enable all the namespace options
> +	  below.
>  
>  config UTS_NS
>  	bool "UTS namespace"
>  	depends on NAMESPACES
>  	help
> -	  In this namespace tasks see different info provided with the
> -	  uname() system call
> +	  Enable support for multiple UTS system attributes.
> +
> +	  Each UTS namespace provides an individual view of the
> +	  information returned by the uname() system call including
> +	  hostname, kernel version and domain name.
> +
> +	  This is used by container systems (i.e. vservers) so that
> +	  each container has its own hostname and other attributes.
> +	  Tasks in the container are placed in the UTS namespace
> +	  corresponding to the container.
> +
> +	  Answer Y if you will be using a container system.
>  
>  config IPC_NS
>  	bool "IPC namespace"
>  	depends on NAMESPACES && SYSVIPC
>  	help
> -	  In this namespace tasks work with IPC ids which correspond to
> -	  different IPC objects in different namespaces
> +	  Enable support for namespace-specific IPC IDs.
> +
> +	  IPC IDs will be unique only within each IPC namespace.
> +
> +	  This is used by container systems (i.e. vservers).
> +	  Tasks in the container are placed in the IPC namespace
> +	  corresponding to the container.
> +
> +	  Answer Y if you will be using a container system.
>  
>  config USER_NS
>  	bool "User namespace (EXPERIMENTAL)"
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  This allows containers, i.e. vservers, to use user namespaces
> -	  to provide different user info for different servers.
> +	  Enable experimental support for user namespaces.
> +
> +	  This is a function used by container-based virtualisation systems
> +	  (e.g. vservers). User namespaces are intended to ensure that
> +	  processes with the same uid which are in different containers are
> +	  isolated from each other.
> +
> +	  Currently user namespaces provide separate accounting, while
> +	  isolation must be provided using SELinux or a custom security
> +	  module.
> +
>  	  If unsure, say N.
>  
>  config PID_NS
> @@ -446,12 +486,20 @@
>  	default n
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  Suport process id namespaces.  This allows having multiple
> -	  process with the same pid as long as they are in different
> -	  pid namespaces.  This is a building block of containers.
> +	  Enable experimental support for hierarchical process id namespaces.
>  
> -	  Unless you want to work with an experimental feature
> -	  say N here.
> +	  Process IDs will be unique only within each PID namespace.
> +	  This allows multiple processes to have the same PID
> +	  so long as they are in different PID namespaces. Furthermore,
> +	  each process will have a distinct PID in each namespace
> +	  the process is in.
> +
> +	  This is used by container systems (i.e. vservers).
> +	  Tasks in the container are placed in the PID namespace
> +	  corresponding to the container, and can only see or
> +	  affect processes in the same PID namespace.

Hi Nick,

thanks for all this work.

Perhaps it would be better to have a Documentation/Namespaces/PID file
describing these semantics, and have the description read something
briefer like

	  Pid namespaces provide filtered views of processes and their
	  process ids.  This features is used to implement containers.
	  Please see Documentation/Namespaces/PID for details.

But in any case with Pavel's comments this looks very good.

thanks,
-serge

> +
> +	  If unsure, say N.
>  
>  config BLK_DEV_INITRD
>  	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"
> --
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/

Re: [PATCH 2.6.25-rc2 3/9] config: Improve init/Kconfig help descriptions - namespaces

[Nick Andrew]

On Wed, Feb 20, 2008 at 10:50:34AM -0600, serge@hallyn.com wrote:
> thanks for all this work.
> 
> Perhaps it would be better to have a Documentation/Namespaces/PID file
> describing these semantics, and have the description read something
> briefer like
> 
> 	  Pid namespaces provide filtered views of processes and their
> 	  process ids.  This features is used to implement containers.
> 	  Please see Documentation/Namespaces/PID for details.
> 
> But in any case with Pavel's comments this looks very good.

I'm sure you're right, but my goal is to improve all the Kconfig help
messages (clarity, accuracy, consistency) and so at this time I want
to limit myself to changes to the help descriptions.

If somebody will add documentation for this or any other subsystem
I will gladly refer to it but in the meantime I'm sure we can come up
with a wording which everybody can agree with.

The point of view I'm coming from is that of a non-kernel-developer
who has to make a choice about some feature of the kernel which they
don't understand. When I'm configuring a kernel I appreciate a bit more
detail in the help text.  I want to provide enough information to help
the user make a rational choice, or give them some idea about what they
are agreeing to put into their kernel. If they still don't understand,
there will be a suggested safe answer.

I'll see if I can make it briefer, if there's any fat which can be
trimmed away.

Current wording:

@@ -446,12 +486,20 @@ config PID_NS
        default n
        depends on NAMESPACES && EXPERIMENTAL
        help
-         Suport process id namespaces.  This allows having multiple
-         process with the same pid as long as they are in different
-         pid namespaces.  This is a building block of containers.
+         Enable experimental support for hierarchical process id namespaces.

-         Unless you want to work with an experimental feature
-         say N here.
+         Process IDs will be unique only within each PID namespace.
+         This allows multiple processes to have the same PID
+         so long as they are in different PID namespaces. Furthermore,
+         each process will have a distinct PID in each namespace
+         the process is in.
+
+         This is used by container systems (i.e. vservers).
+         Tasks in the container are placed in the PID namespace
+         corresponding to the container, and cannot see or
+         affect processes in any parent PID namespaces.
+
+         If unsure, say N.

 config BLK_DEV_INITRD
        bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"


Nick.

Improve init/Kconfig help descriptions [PATCH 4/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 4
> 	AUDIT
> 	AUDITSYSCALL

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>

--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -231,20 +231,36 @@ config AUDIT
 	bool "Auditing support"
 	depends on NET
 	help
-	  Enable auditing infrastructure that can be used with another
-	  kernel subsystem, such as SELinux (which requires this for
-	  logging of avc messages output).  Does not do system-call
-	  auditing without CONFIG_AUDITSYSCALL.
+	  Enable an auditing infrastructure that can be used with another
+	  kernel subsystem, such as Security-Enhanced Linux (SELinux),
+	  which requires this option for logging of AVC messages output.
+
+	  AVC refers to Access Vector Cache, a subsystem used by SELinux
+	  to improve performance of the security checking by caching
+	  previous access decisions.
+
+	  See <http://www.nsa.gov/selinux/> for more information
+	  on Security-Enhanced Linux.
+
+	  CONFIG_AUDITSYSCALL (see below) is also required for
+	  system-call auditing.
+
+	  If unsure, say N.
 
 config AUDITSYSCALL
 	bool "Enable system-call auditing support"
 	depends on AUDIT && (X86 || PPC || PPC64 || S390 || IA64 || UML || SPARC64)
 	default y if SECURITY_SELINUX
 	help
-	  Enable low-overhead system-call auditing infrastructure that
+	  Enable a low-overhead system-call auditing infrastructure that
 	  can be used independently or with another kernel subsystem,
-	  such as SELinux.  To use audit's filesystem watch feature, please
-	  ensure that INOTIFY is configured.
+	  such as SELinux.
+
+	  To use audit's filesystem watch feature, please ensure
+	  that CONFIG_INOTIFY is enabled. See the 'File systems'
+	  menu for Inotify file change notification support.
+
+	  If unsure, say N.
 
 config AUDIT_TREE
 	def_bool y

Re: Improve init/Kconfig help descriptions [PATCH 4/9]

[Valdis.Kletnieks]

[-- Attachment #1: Type: text/plain, Size: 948 bytes --]

On Wed, 20 Feb 2008 01:38:55 +1100, Nick Andrew said:

> +	  Enable an auditing infrastructure that can be used with another
> +	  kernel subsystem, such as Security-Enhanced Linux (SELinux),
> +	  which requires this option for logging of AVC messages output.
> +
> +	  AVC refers to Access Vector Cache, a subsystem used by SELinux
> +	  to improve performance of the security checking by caching
> +	  previous access decisions.

This paragraph can be dropped, as the reasons that SELinux denial messages
are tagged with 'avc' are mostly historical.   If you want to expand on anything
in here, explain that 'AVC' messages are interesting because they indicate
some sort of security rule denial.  So - if you don't enable auditing,
your security messages end up in the kernel syslog.  If you enable auditing,
they end up in the audit logs.  Explaining *that* clearly would be a lot
more useful than explaining what avc originally stood for.. ;)

[-- Attachment #2: Type: application/pgp-signature, Size: 226 bytes --]

Re: Improve init/Kconfig help descriptions [PATCH 4/9]

[Nick Andrew]

On Tue, Feb 19, 2008 at 10:42:10PM -0500, Valdis.Kletnieks@vt.edu wrote:
> On Wed, 20 Feb 2008 01:38:55 +1100, Nick Andrew said:
> > +	  AVC refers to Access Vector Cache, a subsystem used by SELinux
> > +	  to improve performance of the security checking by caching
> > +	  previous access decisions.
> 
> This paragraph can be dropped, as the reasons that SELinux denial messages
> are tagged with 'avc' are mostly historical.   If you want to expand on anything
> in here, explain that 'AVC' messages are interesting because they indicate
> some sort of security rule denial.

Ok, if AVC is incidental then I don't need to mention it, and so don't
need to define the acronym.

> So - if you don't enable auditing,
> your security messages end up in the kernel syslog.  If you enable auditing,
> they end up in the audit logs.  Explaining *that* clearly would be a lot
> more useful than explaining what avc originally stood for.. ;)

How about this. I tried to explain what happens to audit messages.

        bool "Auditing support"
        depends on NET
        help
-         Enable auditing infrastructure that can be used with another
-         kernel subsystem, such as SELinux (which requires this for
-         logging of avc messages output).  Does not do system-call
-         auditing without CONFIG_AUDITSYSCALL.
+         Enable an auditing infrastructure that can be used with another
+         kernel subsystem, such as Security-Enhanced Linux (SELinux),
+         which requires this option for logging of security related
+         messages.
+
+         With this option, the kernel can use netlink to pass audit
+         messages to an audit daemon process. Otherwise, audit messages
+         are logged to syslog.
+
+         See <http://www.nsa.gov/selinux/> for more information
+         on Security-Enhanced Linux.
+
+         CONFIG_AUDITSYSCALL (see below) is also required for
+         system-call auditing.
+
+         If unsure, say N.

I'm puzzled about "end up in the kernel syslog". Looking at include/linux/audit.h
it seems that they go nowhere:

#ifdef CONFIG_AUDIT
  [...]
#else
#define audit_log(c,g,t,f,...) do { ; } while (0)
#define audit_log_start(c,g,t) ({ NULL; })
#define audit_log_vformat(b,f,a) do { ; } while (0)
#define audit_log_format(b,f,...) do { ; } while (0)
#define audit_log_end(b) do { ; } while (0)
#define audit_log_hex(a,b,l) do { ; } while (0)
#define audit_log_untrustedstring(a,s) do { ; } while (0)
#define audit_log_n_untrustedstring(a,n,s) do { ; } while (0)
#define audit_log_d_path(b, p, d) do { ; } while (0)
#define audit_enabled 0
#endif

So it looks like if CONFIG_AUDIT is not defined then audit messages are
ignored. Syslog is used by kernel/audit.c when there is an audit
failure, which seems to be mainly if the userspace audit daemon is not
running.

Nick.

Improve init/Kconfig help descriptions [PATCH 5/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 5
> 	IKCONFIG
> 	IKCONFIG_PROC
> 	LOG_BUF_SHIFT
> 	SYSFS_DEPRECATED
> 	RELAY
> 	BLK_DEV_INITRD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>


--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -254,20 +254,30 @@ config IKCONFIG
 	tristate "Kernel .config support"
 	---help---
 	  This option enables the complete Linux kernel ".config" file
-	  contents to be saved in the kernel. It provides documentation
-	  of which kernel options are used in a running kernel or in an
-	  on-disk kernel.  This information can be extracted from the kernel
-	  image file with the script scripts/extract-ikconfig and used as
-	  input to rebuild the current kernel or to build another kernel.
-	  It can also be extracted from a running kernel by reading
-	  /proc/config.gz if enabled (below).
+	  contents to be saved in the kernel.
+
+	  It provides documentation of which kernel options are used in
+	  a running kernel or in an on-disk kernel.  This information
+	  can be extracted from the kernel image file with the script
+	  "scripts/extract-ikconfig" and used as input to rebuild the
+	  current kernel or to build another kernel.
+
+	  It can also be extracted from a running kernel with
+	  "zcat /proc/config.gz" if CONFIG_IKCONFIG_PROC is enabled
+	  below.
+
+	  Your kernel size will increase by around 14k.
+
+	  If unsure, say N.
 
 config IKCONFIG_PROC
 	bool "Enable access to .config through /proc/config.gz"
 	depends on IKCONFIG && PROC_FS
 	---help---
-	  This option enables access to the kernel configuration file
-	  through /proc/config.gz.
+	  This option enables access to the configuration of the running
+	  kernel through /proc/config.gz.
+
+	  If unsure, say Y.
 
 config LOG_BUF_SHIFT
 	int "Kernel log buffer size (16 => 64KB, 17 => 128KB)"
@@ -277,14 +287,15 @@ config LOG_BUF_SHIFT
 	default 15 if SMP
 	default 14
 	help
-	  Select kernel log buffer size as a power of 2.
-	  Defaults and Examples:
+	  Select the kernel log buffer size as a power of 2.
+
+	  Defaults and examples:
 	  	     17 => 128 KB for S/390
-		     16 => 64 KB for x86 NUMAQ or IA-64
-	             15 => 32 KB for SMP
-	             14 => 16 KB for uniprocessor
-		     13 =>  8 KB
-		     12 =>  4 KB
+		     16 =>  64 KB for x86 NUMAQ or IA-64
+	             15 =>  32 KB for SMP
+	             14 =>  16 KB for uniprocessor
+		     13 =>   8 KB
+		     12 =>   4 KB
 
 config CGROUPS
 	bool "Control Group support"
@@ -389,11 +400,14 @@ config PROC_PID_CPUSET
 config RELAY
 	bool "Kernel->user space relay support (formerly relayfs)"
 	help
-	  This option enables support for relay interface support in
+	  This option enables support for the relay interface in
 	  certain file systems (such as debugfs).
+
 	  It is designed to provide an efficient mechanism for tools and
 	  facilities to relay large amounts of data from kernel space to
-	  user space.
+	  userspace.
+
+	  See <file:Documentation/filesystems/relay.txt> for more information.
 
 	  If unsure, say N.
 
@@ -401,17 +415,24 @@ config BLK_DEV_INITRD
 	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"
 	depends on BROKEN || !FRV
 	help
+	  Enable use of an initial RAM filesystem or RAM disk at boot
+	  time.
+
 	  The initial RAM filesystem is a ramfs which is loaded by the
-	  boot loader (loadlin or lilo) and that is mounted as root
+	  boot loader (loadlin, lilo, grub) and is mounted as root
 	  before the normal boot procedure. It is typically used to
 	  load modules needed to mount the "real" root file system,
-	  etc. See <file:Documentation/initrd.txt> for details.
+	  etc.
+	  
+	  For more information, see:
+	  <file:Documentation/initrd.txt>
+	  <file:Documentation/filesystems/ramfs-rootfs-initramfs.txt>
 
 	  If RAM disk support (BLK_DEV_RAM) is also included, this
 	  also enables initial RAM disk (initrd) support and adds
 	  15 Kbytes (more on some other architectures) to the kernel size.
 
-	  If unsure say Y.
+	  If unsure, say Y.
 
 if BLK_DEV_INITRD
 

Re: Improve init/Kconfig help descriptions [PATCH 5/9]

[Randy Dunlap]

On Wed, 20 Feb 2008 01:53:09 +1100 Nick Andrew wrote:

> On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> > Here is a series of 9 patches to init/Kconfig intended to improve the
> > usefulness and consistency of the help descriptions. The patches are
> > against linux-2.6.24.2.
> > [...]
> > Patch 5
> > 	IKCONFIG
> > 	IKCONFIG_PROC
> > 	LOG_BUF_SHIFT

Those parts are fine.  Acked-by: Randy Dunlap <randy.dunlap@oracle.com>


Please read http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt,
esp. section 2, Subject.


> Changelog:
> 
> Improve usefulness and consistency of kernel configuration help messages.
> 
> Signed-off-by: Nick Andrew <nick@nick-andrew.net>
> 
> 
> --- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
> +++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
> @@ -254,20 +254,30 @@ config IKCONFIG
>  	tristate "Kernel .config support"
>  	---help---
>  	  This option enables the complete Linux kernel ".config" file
> -	  contents to be saved in the kernel. It provides documentation
> -	  of which kernel options are used in a running kernel or in an
> -	  on-disk kernel.  This information can be extracted from the kernel
> -	  image file with the script scripts/extract-ikconfig and used as
> -	  input to rebuild the current kernel or to build another kernel.
> -	  It can also be extracted from a running kernel by reading
> -	  /proc/config.gz if enabled (below).
> +	  contents to be saved in the kernel.
> +
> +	  It provides documentation of which kernel options are used in
> +	  a running kernel or in an on-disk kernel.  This information
> +	  can be extracted from the kernel image file with the script
> +	  "scripts/extract-ikconfig" and used as input to rebuild the
> +	  current kernel or to build another kernel.
> +
> +	  It can also be extracted from a running kernel with
> +	  "zcat /proc/config.gz" if CONFIG_IKCONFIG_PROC is enabled
> +	  below.
> +
> +	  Your kernel size will increase by around 14k.
> +
> +	  If unsure, say N.
>  
>  config IKCONFIG_PROC
>  	bool "Enable access to .config through /proc/config.gz"
>  	depends on IKCONFIG && PROC_FS
>  	---help---
> -	  This option enables access to the kernel configuration file
> -	  through /proc/config.gz.
> +	  This option enables access to the configuration of the running
> +	  kernel through /proc/config.gz.
> +
> +	  If unsure, say Y.
>  
>  config LOG_BUF_SHIFT
>  	int "Kernel log buffer size (16 => 64KB, 17 => 128KB)"
> @@ -277,14 +287,15 @@ config LOG_BUF_SHIFT
>  	default 15 if SMP
>  	default 14
>  	help
> -	  Select kernel log buffer size as a power of 2.
> -	  Defaults and Examples:
> +	  Select the kernel log buffer size as a power of 2.
> +
> +	  Defaults and examples:
>  	  	     17 => 128 KB for S/390
> -		     16 => 64 KB for x86 NUMAQ or IA-64
> -	             15 => 32 KB for SMP
> -	             14 => 16 KB for uniprocessor
> -		     13 =>  8 KB
> -		     12 =>  4 KB
> +		     16 =>  64 KB for x86 NUMAQ or IA-64
> +	             15 =>  32 KB for SMP
> +	             14 =>  16 KB for uniprocessor
> +		     13 =>   8 KB
> +		     12 =>   4 KB
>  
>  config CGROUPS
>  	bool "Control Group support"


---
~Randy

Improve init/Kconfig help descriptions [PATCH 6/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 6
> 	CGROUPS
> 	CGROUP_DEBUG
> 	CPUSETS
> 	FAIR_GROUP_SCHED
> 	FAIR_CGROUP_SCHED
> 	CGROUP_CPUACCT
> 	PROC_PID_CPUSET

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>


--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -289,10 +289,16 @@ config LOG_BUF_SHIFT
 config CGROUPS
 	bool "Control Group support"
 	help
-	  This option will let you use process cgroup subsystems
-	  such as Cpusets
+	  Control Groups enables processes to be tracked and grouped
+	  into "cgroups". This enables you, for example, to associate
+	  cgroups with certain CPU sets using "cpusets".
 
-	  Say N if unsure.
+	  When enabled, a new filesystem type "cgroup" is available
+	  and can be mounted to control cpusets.
+
+	  See <file:Documentation/cgroups.txt> for more information.
+
+	  If unsure, say N.
 
 config CGROUP_DEBUG
 	bool "Example debug cgroup subsystem"
@@ -300,9 +306,9 @@ config CGROUP_DEBUG
 	help
 	  This option enables a simple cgroup subsystem that
 	  exports useful debugging information about the cgroups
-	  framework
+	  framework.
 
-	  Say N if unsure
+	  If unsure, say N.
 
 config CGROUP_NS
         bool "Namespace cgroup subsystem"
@@ -317,19 +323,24 @@ config CPUSETS
 	bool "Cpuset support"
 	depends on SMP && CGROUPS
 	help
-	  This option will let you create and manage CPUSETs which
+	  This option will let you create and manage "cpusets" which
 	  allow dynamically partitioning a system into sets of CPUs and
 	  Memory Nodes and assigning tasks to run only within those sets.
+
 	  This is primarily useful on large SMP or NUMA systems.
 
-	  Say N if unsure.
+	  See <file:Documentation/cpusets.txt> for more information.
+
+	  If unsure, say N.
 
 config FAIR_GROUP_SCHED
 	bool "Fair group CPU scheduler"
 	default y
 	help
-	  This feature lets CPU scheduler recognize task groups and control CPU
-	  bandwidth allocation to such task groups.
+	  This feature enables the CPU scheduler to recognize task groups
+	  and control CPU bandwidth allocation to such task groups.
+
+	  See <file:Documentation/sched-design-CFS.txt> for more information.
 
 choice
 	depends on FAIR_GROUP_SCHED
@@ -348,9 +359,10 @@ config FAIR_CGROUP_SCHED
  	help
 	  This option allows you to create arbitrary task groups
 	  using the "cgroup" pseudo filesystem and control
-	  the cpu bandwidth allocated to each such task group.
-	  Refer to Documentation/cgroups.txt for more information
-	  on "cgroup" pseudo filesystem.
+	  the CPU bandwidth allocated to each such task group.
+
+	  See <file:Documentation/cgroups.txt> for more information
+	  on the "cgroup" pseudo filesystem.
 
 endchoice
 
@@ -359,7 +371,7 @@ config CGROUP_CPUACCT
 	depends on CGROUPS
 	help
 	  Provides a simple Resource Controller for monitoring the
-	  total CPU consumed by the tasks in a cgroup
+	  total CPU consumed by the tasks in a cgroup.
 
 config SYSFS_DEPRECATED
 	bool "Create deprecated sysfs files"
@@ -369,6 +381,7 @@ config SYSFS_DEPRECATED
 	  "device"-link, the <subsystem>:<name>-link, and the
 	  "bus"-link. It may also add deprecated key in the
 	  uevent environment.
+
 	  None of these features or values should be used today, as
 	  they export driver core implementation details to userspace
 	  or export properties which can't be kept stable across kernel
@@ -381,10 +394,20 @@ config SYSFS_DEPRECATED
 	  If you are using a distro that was released in 2006 or later,
 	  it should be safe to say N here.
 
+	  If unsure, say N.
+
 config PROC_PID_CPUSET
 	bool "Include legacy /proc/<pid>/cpuset file"
 	depends on CPUSETS
 	default y
+	help
+	  This option provides the legacy /proc/<pid>/cpuset file.
+
+	  It has been deprecated in favour of an additional line
+	  in /proc/<pid>/status showing on which CPUs a process
+	  may be scheduled.
+
+	  If unsure, say Y.
 
 config RELAY
 	bool "Kernel->user space relay support (formerly relayfs)"

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[Paul Jackson]

Thanks for doing this, Nick.  One area looks like some details
need working.

Nick Andrew wrote:
>  config PROC_PID_CPUSET
>  	bool "Include legacy /proc/<pid>/cpuset file"
>  	depends on CPUSETS
>  	default y
> +	help
> +	  This option provides the legacy /proc/<pid>/cpuset file.
> +
> +	  It has been deprecated in favour of an additional line
> +	  in /proc/<pid>/status showing on which CPUs a process
> +	  may be scheduled.

I don't think /proc/<pid>/cpuset (PROC_PID_CPUSET) is, or should be,
deprecated.

Actually, I'd be inclined toward removing this CONFIG option, and
making /proc/<pid>/cpuset a non-optional consequence of enabling
cpusets ... so I'm adding Paul Menage to the CC list, in case he has
thoughts or insights on this.  The duplication of this bit of information
between both /proc/<pid>/cpuset and one line of /proc/<pid>/status is a
minor and harmless wart, resulting from the evolution of cgroups from
cpusets, that is not worth bothering kernel configuration users with
questions about.

And isn't that a line in /proc/<pid>/cgroup, not in /proc/<pid>/status ?

-- 
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <pj@sgi.com> 1.940.382.4214

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[Nick Andrew]

On Tue, Feb 19, 2008 at 09:39:58AM -0600, Paul Jackson wrote:
> I don't think /proc/<pid>/cpuset (PROC_PID_CPUSET) is, or should be,
> deprecated.

Ok, I had just picked up on the "legacy" word in the option title
and assumed that it meant deprecated.

This is what I've got now:

 config PROC_PID_CPUSET
        bool "Include legacy /proc/<pid>/cpuset file"
        depends on CPUSETS
        default y
+       help
+         This option provides the /proc/<pid>/cpuset file.
+
+         This file contains the name of the cpuset in which
+         the process is executing. For more information, see
+         <file:Documentation/cpusets.txt>
+
+         If unsure, say Y.

In general, are option titles fragile? For example, if I were to submit
a patch which changes an option's title string, is this likely to break
something or somebody?

Nick.

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[Paul Jackson]

Nick wrote:
> Ok, I had just picked up on the "legacy" word in the option title
> and assumed that it meant deprecated.

Just because something's old (and some newer equivalent exists)
doesn't mean we're making funeral arrangements for it yet.

	Paul "old man" Jackson


-- 
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <pj@sgi.com> 1.940.382.4214

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[Paul Menage]

On Feb 19, 2008 7:12 AM, Nick Andrew <nick@nick-andrew.net> wrote:
>  config CGROUPS
>         bool "Control Group support"
>         help
> -         This option will let you use process cgroup subsystems
> -         such as Cpusets
> +         Control Groups enables processes to be tracked and grouped
> +         into "cgroups". This enables you, for example, to associate
> +         cgroups with certain CPU sets using "cpusets".
>
> -         Say N if unsure.
> +         When enabled, a new filesystem type "cgroup" is available
> +         and can be mounted to control cpusets.

How about:

... cpusets and other resource/behaviour controllers.

Paul

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[Nick Andrew]

On Tue, Feb 19, 2008 at 06:04:57PM -0800, Paul Menage wrote:
> On Feb 19, 2008 7:12 AM, Nick Andrew <nick@nick-andrew.net> wrote:
> >  config CGROUPS
> > [...]
> > +         When enabled, a new filesystem type "cgroup" is available
> > +         and can be mounted to control cpusets.
> How about:
> ... cpusets and other resource/behaviour controllers.

Ok I added that. This is what I have now:


config CGROUPS
        bool "Control Group support"
        help
	  Control Groups enables processes to be tracked and grouped
	  into "cgroups". This enables you, for example, to associate
	  cgroups with certain CPU sets using "cpusets".

	  When enabled, a new filesystem type "cgroup" is available
	  and can be mounted to control cpusets and other
	  resource/behaviour controllers.

	  See <file:Documentation/cgroups.txt> for more information.

	  If unsure, say N.


I don't think that description is as clear as it could be. From
the non-kernel-developer point of view, that is. I'll read
Documentation/cgroups.txt more thoroughly and see if I can come
up with a better description.

Re "other resource/behaviour controllers", what in particular?
I take it that our current controllers are cpusets, scheduler,
CPU accounting and Resource counters?

Nick.

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[Paul Menage]

On Feb 19, 2008 6:54 PM, Nick Andrew <nick@nick-andrew.net> wrote:
>
> config CGROUPS
>         bool "Control Group support"
>         help
>           Control Groups enables processes to be tracked and grouped
>           into "cgroups". This enables you, for example, to associate
>           cgroups with certain CPU sets using "cpusets".
>
>           When enabled, a new filesystem type "cgroup" is available
>           and can be mounted to control cpusets and other
>           resource/behaviour controllers.
>
>           See <file:Documentation/cgroups.txt> for more information.
>
>           If unsure, say N.
>
>
> I don't think that description is as clear as it could be. From
> the non-kernel-developer point of view, that is.

Originally this wasn't a user-selectable config value, it was
auto-selected by any subsystem that needed it. I think that was nicer
from the user-experience, and it would eliminate the need for this
documentation but there were concerns that this triggered unspecified
brokenness in the Kbuild system.

>
> Re "other resource/behaviour controllers", what in particular?
> I take it that our current controllers are cpusets, scheduler,
> CPU accounting and Resource counters?

Resource counters aren't a resource controller, they're a helper
library. The others are good examples, as is the memory controller
that's just been added to 2.6.25.

Paul

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[serge]

Quoting Nick Andrew (nick@nick-andrew.net):
> On Tue, Feb 19, 2008 at 06:04:57PM -0800, Paul Menage wrote:
> > On Feb 19, 2008 7:12 AM, Nick Andrew <nick@nick-andrew.net> wrote:
> > >  config CGROUPS
> > > [...]
> > > +         When enabled, a new filesystem type "cgroup" is available
> > > +         and can be mounted to control cpusets.
> > How about:
> > ... cpusets and other resource/behaviour controllers.
> 
> Ok I added that. This is what I have now:
> 
> 
> config CGROUPS
>         bool "Control Group support"
>         help
> 	  Control Groups enables processes to be tracked and grouped
> 	  into "cgroups". This enables you, for example, to associate

Maybe 
	  Control Groups enable processes to be grouped into "cgroups"
	  to facilitate tracking and resource management.  For example
	  a cgroup can tie a set of processes to a set of cpus using
	  "cpusets".

> 	  When enabled, a new filesystem type "cgroup" is available
> 	  and can be mounted to control cpusets and other
> 	  resource/behaviour controllers.
> 
> 	  See <file:Documentation/cgroups.txt> for more information.
> 
> 	  If unsure, say N.
> 
> 
> I don't think that description is as clear as it could be. From
> the non-kernel-developer point of view, that is. I'll read
> Documentation/cgroups.txt more thoroughly and see if I can come
> up with a better description.
> 
> Re "other resource/behaviour controllers", what in particular?
> I take it that our current controllers are cpusets, scheduler,
> CPU accounting and Resource counters?
> 
> Nick.
> --
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/

Re: Improve init/Kconfig help descriptions [PATCH 6/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 10:55:07AM -0600, serge@hallyn.com wrote:
> Quoting Nick Andrew (nick@nick-andrew.net):
> > On Tue, Feb 19, 2008 at 06:04:57PM -0800, Paul Menage wrote:
> 
> Maybe 
> 	  Control Groups enable processes to be grouped into "cgroups"
> 	  to facilitate tracking and resource management.  For example
> 	  a cgroup can tie a set of processes to a set of cpus using
> 	  "cpusets".

That is much nicer, thanks.

> > 	  When enabled, a new filesystem type "cgroup" is available
> > 	  and can be mounted to control cpusets and other
> > 	  resource/behaviour controllers.

I thought of something better to say than this.  Enabling a new
pseudo filesystem is interesting, but it's not the main point.

Now:


 config CGROUPS
        bool "Control Group support"
        help
-         This option will let you use process cgroup subsystems
-         such as Cpusets
+         Control Groups enable processes to be grouped into "cgroups"
+         to facilitate tracking and resource management. For example
+         a cgroup can tie a set of processes to a set of CPUs using
+         "cpusets".

-         Say N if unsure.
+         See <file:Documentation/cgroups.txt> for more information.
+
+         If you say Y here, you probably want to enable one or
+         more of the cgroup subsystem options below.
+
+         If unsure, say N.


Regarding GROUP_SCHED and CGROUP_SCHED I am confused, what is the
difference between these two options?

config GROUP_SCHED
        bool "Group CPU scheduler"
        default y
        help
          This feature enables the CPU scheduler to recognize task groups
          and control CPU bandwidth allocation to such task groups.

          See <file:Documentation/sched-design-CFS.txt> for more information.


[...]

config CGROUP_SCHED
        bool "Control groups"
        depends on CGROUPS
        help
          This option allows you to create arbitrary task groups
          using the "cgroup" pseudo filesystem and control
          the CPU bandwidth allocated to each such task group.

          See <file:Documentation/cgroups.txt> for more information
          on the "cgroup" pseudo filesystem.

Also with the titles, IMHO "Control Group support" is semantically
equivalent to "Control groups" so I am doubly confused.

Nick.

Improve init/Kconfig help descriptions [PATCH 7/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 7
> 	EMBEDDED
> 	SYSCTL_SYSCALL
> 	KALLSYMS
> 	KALLSYMS_ALL
> 	KALLSYMS_EXTRA_PASS
> 	HOTPLUG
> 	PRINTK
> 	BUG
> 	ELF_CORE
> 	BASE_FULL
> 	FUTEX
> 	EPOLL
> 	SIGNALFD
> 	TIMERFD
> 	EVENTFD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>

--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -439,10 +439,14 @@ menuconfig EMBEDDED
 	bool "Configure standard kernel features (for small systems)"
 	help
 	  This option allows certain base kernel options and settings
-          to be disabled or tweaked. This is for specialized
-          environments which can tolerate a "non-standard" kernel.
+	  to be disabled or tweaked. This is for embedded systems and
+	  specialized environments which can tolerate a "non-standard"
+	  kernel.
+
           Only use this if you really know what you are doing.
 
+	  If unsure, say N.
+
 config UID16
 	bool "Enable 16-bit UID system calls" if EMBEDDED
 	depends on ARM || BLACKFIN || CRIS || FRV || H8300 || X86_32 || M68K || (S390 && !64BIT) || SUPERH || SPARC32 || (SPARC64 && SPARC32_COMPAT) || UML || (X86_64 && IA32_EMULATION)
@@ -460,51 +464,62 @@ config SYSCTL_SYSCALL
 	  using paths with ascii names is now the primary path to this
 	  information.
 
-	  Almost nothing using the binary sysctl interface so if you are
+	  Almost nothing uses the binary sysctl interface so if you are
 	  trying to save some space it is probably safe to disable this,
 	  making your kernel marginally smaller.
 
-	  If unsure say Y here.
+	  If unsure, say Y.
 
 config KALLSYMS
-	 bool "Load all symbols for debugging/ksymoops" if EMBEDDED
-	 default y
-	 help
-	   Say Y here to let the kernel print out symbolic crash information and
-	   symbolic stack backtraces. This increases the size of the kernel
-	   somewhat, as all symbols have to be loaded into the kernel image.
+	bool "Load all symbols for debugging/ksymoops" if EMBEDDED
+	default y
+	help
+	  This information causes the kernel to print out symbolic crash
+	  information and symbolic stack backtraces.
+
+	  It increases the size of the kernel somewhat, as all symbols
+	  have to be loaded into the kernel image.
+
+	  If unsure, say Y.
 
 config KALLSYMS_ALL
 	bool "Include all symbols in kallsyms"
 	depends on DEBUG_KERNEL && KALLSYMS
 	help
-	   Normally kallsyms only contains the symbols of functions, for nicer
-	   OOPS messages.  Some debuggers can use kallsyms for other
-	   symbols too: say Y here to include all symbols, if you need them 
-	   and you don't care about adding 300k to the size of your kernel.
+	  Normally kallsyms only contains the symbols of functions, for nicer
+	  OOPS messages.  Some debuggers can use kallsyms for other
+	  symbols too: say Y here to include all symbols, if you need them.
+
+	  Your kernel size will increase by around 300k.
 
-	   Say N.
+	  If unsure, say N.
 
 config KALLSYMS_EXTRA_PASS
 	bool "Do an extra kallsyms pass"
 	depends on KALLSYMS
 	help
-	   If kallsyms is not working correctly, the build will fail with
-	   inconsistent kallsyms data.  If that occurs, log a bug report and
-	   turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
-	   Always say N here unless you find a bug in kallsyms, which must be
-	   reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
-	   you wait for kallsyms to be fixed.
+	  If kallsyms is not working correctly, the build will fail with
+	  inconsistent kallsyms data.  If that occurs, log a bug report and
+	  turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
+
+	  Always say N here unless you find a bug in kallsyms, which must be
+	  reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
+	  you wait for kallsyms to be fixed.
 
+	  If unsure, say N.
 
 config HOTPLUG
 	bool "Support for hot-pluggable devices" if EMBEDDED
 	default y
 	help
 	  This option is provided for the case where no hotplug or uevent
-	  capabilities is wanted by the kernel.  You should only consider
-	  disabling this option for embedded systems that do not use modules, a
-	  dynamic /dev tree, or dynamic device discovery.  Just say Y.
+	  capabilities are wanted by the kernel.
+
+	  You should only consider disabling this option for embedded
+	  systems that do not use modules, a dynamic /dev tree, or
+	  dynamic device discovery.
+
+	  If unsure, say Y.
 
 config PRINTK
 	default y
@@ -516,21 +531,30 @@ config PRINTK
 	  very difficult to diagnose system problems, saying N here is
 	  strongly discouraged.
 
+	  If unsure, say Y.
+
 config BUG
 	bool "BUG() support" if EMBEDDED
 	default y
 	help
           Disabling this option eliminates support for BUG and WARN, reducing
           the size of your kernel image and potentially quietly ignoring
-          numerous fatal conditions. You should only consider disabling this
-          option for embedded systems with no facilities for reporting errors.
-          Just say Y.
+          numerous fatal conditions.
+
+	  You should only consider disabling this option for embedded
+	  systems with no facilities for reporting errors.
+
+	  If unsure, say Y.
 
 config ELF_CORE
 	default y
 	bool "Enable ELF core dumps" if EMBEDDED
 	help
-	  Enable support for generating core dumps. Disabling saves about 4k.
+	  Enable support for generating core dumps when a process fails.
+
+	  Your kernel size will increase by around 4k.
+
+	  If unsure, say Y.
 
 config BASE_FULL
 	default y
@@ -540,6 +564,8 @@ config BASE_FULL
 	  kernel data structures. This saves memory on small machines,
 	  but may reduce performance.
 
+	  If unsure, say Y.
+
 config FUTEX
 	bool "Enable futex support" if EMBEDDED
 	default y
@@ -549,6 +575,8 @@ config FUTEX
 	  support for "fast userspace mutexes".  The resulting kernel may not
 	  run glibc-based applications correctly.
 
+	  If unsure, say Y.
+
 config ANON_INODES
 	bool
 
@@ -560,13 +588,15 @@ config EPOLL
 	  Disabling this option will cause the kernel to be built without
 	  support for epoll family of system calls.
 
+	  If unsure, say Y.
+
 config SIGNALFD
 	bool "Enable signalfd() system call" if EMBEDDED
 	select ANON_INODES
 	default y
 	help
-	  Enable the signalfd() system call that allows to receive signals
-	  on a file descriptor.
+	  Enable the signalfd() system call that allows a process to
+	  receive signals on a file descriptor.
 
 	  If unsure, say Y.
 
@@ -576,8 +606,8 @@ config TIMERFD
 	depends on BROKEN
 	default y
 	help
-	  Enable the timerfd() system call that allows to receive timer
-	  events on a file descriptor.
+	  Enable the timerfd() system call that allows a process to
+	  receive timer events on a file descriptor.
 
 	  If unsure, say Y.
 
@@ -586,8 +616,9 @@ config EVENTFD
 	select ANON_INODES
 	default y
 	help
-	  Enable the eventfd() system call that allows to receive both
-	  kernel notification (ie. KAIO) or userspace notifications.
+	  Enable the eventfd() system call that allows a process to
+	  receive both kernel notification (ie. KAIO) or userspace
+	  notifications.
 
 	  If unsure, say Y.
 

Improve init/Kconfig help descriptions [PATCH 8/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 8
> 	SLUB_DEBUG
> 	SLAB
> 	SLUB
> 	SLOB

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>


--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -616,31 +616,48 @@ config SLUB_DEBUG
 	bool "Enable SLUB debugging support" if EMBEDDED
 	depends on SLUB
 	help
+	  Enable debugging on the "SLUB" slab allocator.
+
 	  SLUB has extensive debug support features. Disabling these can
 	  result in significant savings in code size. This also disables
 	  SLUB sysfs support. /sys/slab will not exist and there will be
 	  no support for cache validation etc.
 
+	  If unsure, say N.
+
 choice
 	prompt "Choose SLAB allocator"
 	default SLUB
 	help
-	   This option allows to select a slab allocator.
+	   This option selects a slab allocator.
+
+	   A slab is a contiguous area of kernel memory. Slabs are of
+	   fixed size (1 or more times the page size) and are used as
+	   the container for allocation of kernel data structures. This
+	   reduces memory fragmentation and makes allocation very fast,
+	   improving kernel performance.
+
+	   "SLUB" is the default slab allocator.
+
+	   See wikipedia:Slab_allocation for more details.
 
 config SLAB
 	bool "SLAB"
 	help
-	  The regular slab allocator that is established and known to work
-	  well in all environments. It organizes cache hot objects in
-	  per cpu and per node queues. SLAB is the default choice for
-	  a slab allocator.
+	  SLAB is the original slab allocator that is established and
+	  known to work well in all environments. It organizes cache
+	  hot objects in per-CPU and per-node queues.
+
+	  SLAB has been superseded by SLUB.
 
 config SLUB
 	bool "SLUB (Unqueued Allocator)"
 	help
 	   SLUB is a slab allocator that minimizes cache line usage
-	   instead of managing queues of cached objects (SLAB approach).
-	   Per cpu caching is realized using slabs of objects instead
+	   instead of managing queues of cached objects (the SLAB
+	   approach).
+
+	   Per-CPU caching is realized using slabs of objects instead
 	   of queues of objects. SLUB can use memory efficiently
 	   and has enhanced diagnostics.
 
@@ -648,11 +665,14 @@ config SLOB
 	depends on EMBEDDED
 	bool "SLOB (Simple Allocator)"
 	help
-	   SLOB replaces the SLAB allocator with a drastically simpler
-	   allocator.  SLOB is more space efficient than SLAB but does not
-	   scale well (single lock for all operations) and is also highly
-	   susceptible to fragmentation. SLUB can accomplish a higher object
-	   density. It is usually better to use SLUB instead of SLOB.
+	   SLOB is a drastically simpler allocator for use in embedded
+	   systems.
+
+	   SLOB is more space efficient than SLAB but does not scale well
+	   (it uses a single lock for all operations) and is also highly
+	   susceptible to fragmentation. SLUB can accomplish a higher
+	   object density. It is usually better to use SLUB instead
+	   of SLOB.
 
 endchoice
 

Improve init/Kconfig help descriptions [PATCH 9/9]

[Nick Andrew]

On Wed, Feb 20, 2008 at 01:06:09AM +1100, Nick Andrew wrote:
> Here is a series of 9 patches to init/Kconfig intended to improve the
> usefulness and consistency of the help descriptions. The patches are
> against linux-2.6.24.2.
> [...]
> Patch 9
> 	MODULES
> 	MODULE_UNLOAD
> 	MODULE_FORCE_UNLOAD
> 	MODVERSIONS
> 	MODULE_SRCVERSION_ALL
> 	KMOD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>

--- a/init/Kconfig	2008-02-20 00:45:07.000000000 +1100
+++ b/init/Kconfig	2008-02-20 00:52:07.000000000 +1100
@@ -680,20 +680,26 @@ config BASE_SMALL
 menuconfig MODULES
 	bool "Enable loadable module support"
 	help
-	  Kernel modules are small pieces of compiled code which can
-	  be inserted in the running kernel, rather than being
-	  permanently built into the kernel.  You use the "modprobe"
-	  tool to add (and sometimes remove) them.  If you say Y here,
-	  many parts of the kernel can be built as modules (by
-	  answering M instead of Y where indicated): this is most
-	  useful for infrequently used options which are not required
-	  for booting.  For more information, see the man pages for
-	  modprobe, lsmod, modinfo, insmod and rmmod.
-
-	  If you say Y here, you will need to run "make
-	  modules_install" to put the modules under /lib/modules/
-	  where modprobe can find them (you may need to be root to do
-	  this).
+	  This option allows the kernel to load Kernel modules
+	  at runtime to increase functionality, support new
+	  devices and so on.
+
+	  Kernel modules are compiled code such as device drivers
+	  and filesystems. You can use the "lsmod" command to see
+	  what modules are currently loaded, and "modprobe" to
+	  add (and sometimes remove) them.
+
+	  If you say Y here, many parts of the kernel can be built as
+	  modules (by answering M instead of Y where indicated). This
+	  reduces the size of the compiled kernel and allows you to
+	  choose at runtime which modules will be loaded. With some
+	  other options enabled, module loading and unloading can be
+	  performed automatically by the kernel upon demand.
+
+	  If you say Y here, you will need to run "make modules_install"
+	  after building the kernel to put the modules under /lib/modules/
+	  where "modprobe" can find them. You probably need to be root to
+	  install the modules.
 
 	  If unsure, say Y.
 
@@ -701,10 +707,16 @@ config MODULE_UNLOAD
 	bool "Module unloading"
 	depends on MODULES
 	help
-	  Without this option you will not be able to unload any
-	  modules (note that some modules may not be unloadable
-	  anyway), which makes your kernel slightly smaller and
-	  simpler.  If unsure, say Y.
+	  This option allows the kernel to unload unused modules.
+
+	  A module can only be unloaded if it is not in use by
+	  other modules, the kernel or running processes (for
+	  example, using a device through the module).
+
+	  Disabling this option will make the kernel slightly
+	  smaller and simpler.
+
+	  If unsure, say Y.
 
 config MODULE_FORCE_UNLOAD
 	bool "Forced module unloading"
@@ -714,6 +726,7 @@ config MODULE_FORCE_UNLOAD
 	  kernel believes it is unsafe: the kernel will remove the module
 	  without waiting for anyone to stop using it (using the -f option to
 	  rmmod).  This is mainly for kernel developers and desperate users.
+
 	  If unsure, say N.
 
 config MODVERSIONS
@@ -724,8 +737,9 @@ config MODVERSIONS
 	  Saying Y here makes it sometimes possible to use modules
 	  compiled for different kernels, by adding enough information
 	  to the modules to (hopefully) spot any changes which would
-	  make them incompatible with the kernel you are running.  If
-	  unsure, say N.
+	  make them incompatible with the kernel you are running.
+	  
+	  If unsure, say N.
 
 config MODULE_SRCVERSION_ALL
 	bool "Source checksum for all modules"
@@ -733,11 +747,15 @@ config MODULE_SRCVERSION_ALL
 	help
 	  Modules which contain a MODULE_VERSION get an extra "srcversion"
 	  field inserted into their modinfo section, which contains a
-    	  sum of the source files which made it.  This helps maintainers
-	  see exactly which source was used to build a module (since
-	  others sometimes change the module source without updating
-	  the version).  With this option, such a "srcversion" field
-	  will be created for all modules.  If unsure, say N.
+	  checksum (using the MD4 algorithm) of the source files which
+	  made it.
+
+	  This helps maintainers see exactly which source was used
+	  to build a module (since others sometimes change the module
+	  source without updating the version).  With this option, such
+	  a "srcversion" field will be created for all modules.
+
+	  If unsure, say N.
 
 config KMOD
 	bool "Automatic kernel module loading"
@@ -745,11 +763,14 @@ config KMOD
 	help
 	  Normally when you have selected some parts of the kernel to
 	  be created as kernel modules, you must load them (using the
-	  "modprobe" command) before you can use them. If you say Y
-	  here, some parts of the kernel will be able to load modules
-	  automatically: when a part of the kernel needs a module, it
-	  runs modprobe with the appropriate arguments, thereby
-	  loading the module if it is available.  If unsure, say Y.
+	  "modprobe" command) before you can use them.
+
+	  If you say Y here, some parts of the kernel will be able to
+	  load modules automatically: when a part of the kernel needs a
+	  module, it will run modprobe with the appropriate arguments,
+	  thereby loading the module if it is available.
+
+	  If unsure, say Y.
 
 config STOP_MACHINE
 	bool

[PATCH 2.6.25-rc2 1/9] init: Improve init/Kconfig help descriptions part 1

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

The problems I can see with the supplied help descriptions fall into
these areas:

  - Uses arcane terminology which only kernel developers can understand

  - Inconsistently describes safe response (if unsure, ...)

  - References out-of-date external resources (404 error)

  - Description has not kept pace with recent kernel changes or standards

  - Poor grammar or layout.


My approach to improving the descriptions is to go through each option
checking the correctness of the description, validating any references
it makes, finding inconsistency with the rest of the kernel config,
and trying to improve the usefulness of the explanation. I want to
end up with:

  1 - Single sentence summary of what the option does

  2 - Explain terminology or situation if necessary and possible, linking
  to validated information sources (Documentation directory, manpages,
  scripts, URLs, Wikipedia)

  3 - Suggest safe answer for people who just don't know what to do.


Kernel config options affected:

  - EXPERIMENTAL
  - LOCALVERSION
  - LOCALVERSION_AUTO
  - SWAP
  - SYSVIPC
  - POSIX_MQUEUE
  - BSD_PROCESS_ACCT
  - BSD_PROCESS_ACCT_V3

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Here's try #2 at the 1st patch in the series.
Any comments?


--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-20 09:35:08.000000000 +1100
@@ -20,33 +20,45 @@ menu "General setup"
 config EXPERIMENTAL
 	bool "Prompt for development and/or incomplete code/drivers"
 	---help---
-	  Some of the various things that Linux supports (such as network
-	  drivers, file systems, network protocols, etc.) can be in a state
-	  of development where the functionality, stability, or the level of
-	  testing is not yet high enough for general use. This is usually
-	  known as the "alpha-test" phase among developers. If a feature is
-	  currently in alpha-test, then the developers usually discourage
-	  uninformed widespread use of this feature by the general public to
-	  avoid "Why doesn't this work?" type mail messages. However, active
-	  testing and use of these systems is welcomed. Just be aware that it
-	  may not meet the normal level of reliability or it may fail to work
-	  in some special cases. Detailed bug reports from people familiar
-	  with the kernel internals are usually welcomed by the developers
-	  (before submitting bug reports, please read the documents
-	  <file:README>, <file:MAINTAINERS>, <file:REPORTING-BUGS>,
-	  <file:Documentation/BUG-HUNTING>, and
-	  <file:Documentation/oops-tracing.txt> in the kernel source).
+	  This option enables you to choose kernel configuration
+	  options labeled as EXPERIMENTAL.
+
+	  Some of the various things that Linux supports (such as
+	  network drivers, file systems, network protocols, etc.) can
+	  be in a state of development where the functionality,
+	  stability, or the level of testing is not yet high enough
+	  for general use. This is usually known as the "alpha-test"
+	  phase among developers.
+
+	  If a feature is currently in alpha-test, then the
+	  developers usually discourage uninformed widespread use of
+	  this feature by the general public to avoid "Why doesn't
+	  this work?" type email messages. However, active testing
+	  and use of these systems is welcomed. Just be aware that
+	  it may not meet the normal level of reliability or it
+	  may fail to work in some special cases.
+
+	  Detailed bug reports from people familiar with
+	  the kernel internals are usually welcomed by the
+	  developers. Before submitting bug reports, please
+	  read the documents <file:README>, <file:MAINTAINERS>,
+	  <file:REPORTING-BUGS>, <file:Documentation/BUG-HUNTING>,
+	  and <file:Documentation/oops-tracing.txt> in the kernel
+	  source.
 
 	  This option will also make obsoleted drivers available. These are
 	  drivers that have been replaced by something else, and/or are
 	  scheduled to be removed in a future kernel release.
 
-	  Unless you intend to help test and develop a feature or driver that
-	  falls into this category, or you have a situation that requires
-	  using these features, you should probably say N here, which will
-	  cause the configurator to present you with fewer choices. If
-	  you say Y here, you will be offered the choice of using features or
-	  drivers that are currently considered to be in the alpha-test phase.
+	  Unless you intend to help test and develop a feature or driver
+	  that falls into this category, or you have a situation that
+	  requires using these features, you should probably say N here,
+	  which will cause the configurator to present you with fewer
+	  choices. If you say Y here, you will be offered the choice of
+	  using features or drivers that are currently considered to be
+	  in the alpha-test phase.
+
+	  If unsure, say N.
 
 config BROKEN
 	bool
@@ -74,11 +86,18 @@ config LOCALVERSION
 	string "Local version - append to kernel release"
 	help
 	  Append an extra string to the end of your kernel version.
-	  This will show up when you type uname, for example.
-	  The string you set here will be appended after the contents of
-	  any files with a filename matching localversion* in your
-	  object and source tree, in that order.  Your total string can
-	  be a maximum of 64 characters.
+	  This will show up when you type "uname -r", for example.
+
+	  If you have any files with names matching "localversion*"
+	  in your object or source trees, then the contents of these
+	  files will be appended to your kernel version name.
+
+	  The strings are appended from the object tree files and
+	  then the source tree files, then any string specified
+	  by CONFIG_LOCALVERSION_AUTO below, and finally the value
+	  specified here.
+
+	  The maximum length of a kernel version name is 64 characters.
 
 config LOCALVERSION_AUTO
 	bool "Automatically append version information to the version string"
@@ -93,38 +112,47 @@ config LOCALVERSION_AUTO
 	  appended after any matching localversion* files, and after the value
 	  set in CONFIG_LOCALVERSION.
 
-	  (The actual string used here is the first eight characters produced
+	  The actual string used here is the first eight characters produced
 	  by running the command:
 
 	    $ git rev-parse --verify HEAD
 
-	  which is done within the script "scripts/setlocalversion".)
+	  which is done within the script "scripts/setlocalversion".
 
 config SWAP
 	bool "Support for paging of anonymous memory (swap)"
 	depends on MMU && BLOCK
 	default y
 	help
-	  This option allows you to choose whether you want to have support
-	  for so called swap devices or swap files in your kernel that are
-	  used to provide more virtual memory than the actual RAM present
-	  in your computer.  If unsure say Y.
+	  This option allows you to choose whether you want to have
+	  support for swap devices or swap files in your kernel.
+
+	  Swap is used to provide more virtual memory than the
+	  actual RAM present in your computer. This can improve
+	  performance by moving less frequently used blocks of
+	  memory onto disk, which frees it up for improved disk
+	  caching or active processes.
+
+	  If unsure, say Y.
 
 config SYSVIPC
 	bool "System V IPC"
 	---help---
-	  Inter Process Communication is a suite of library functions and
+	  Inter-Process Communication is a suite of library functions and
 	  system calls which let processes (running programs) synchronize and
 	  exchange information. It is generally considered to be a good thing,
-	  and some programs won't run unless you say Y here. In particular, if
-	  you want to run the DOS emulator dosemu under Linux (read the
-	  DOSEMU-HOWTO, available from <http://www.tldp.org/docs.html#howto>),
-	  you'll need to say Y here.
+	  and some programs won't run without it.
+
+	  In particular, if you want to run the DOS emulator dosemu
+	  under Linux, you'll need to say Y here. You can find out
+	  more about dosemu at <http://dosemu.sourceforge.net/>
 
 	  You can find documentation about IPC with "info ipc" and also in
 	  section 6.4 of the Linux Programmer's Guide, available from
 	  <http://www.tldp.org/guides.html>.
 
+	  If unsure, say Y.
+
 config SYSVIPC_SYSCTL
 	bool
 	depends on SYSVIPC
@@ -135,42 +163,69 @@ config POSIX_MQUEUE
 	bool "POSIX Message Queues"
 	depends on NET && EXPERIMENTAL
 	---help---
-	  POSIX variant of message queues is a part of IPC. In POSIX message
-	  queues every message has a priority which decides about succession
-	  of receiving it by a process. If you want to compile and run
-	  programs written e.g. for Solaris with use of its POSIX message
-	  queues (functions mq_*) say Y here.
-
-	  POSIX message queues are visible as a filesystem called 'mqueue'
-	  and can be mounted somewhere if you want to do filesystem
-	  operations on message queues.
+	  POSIX Message Queues is a type of Inter-Process Communication
+	  (IPC). It provides similar functionality to System V message
+	  queues, with a different Application Programming Interface (API).
+
+	  In POSIX Message Queues, every message has a priority which
+	  determines the order in which each message is delivered to a
+	  receiving process. See mq_overview(7) for details of the
+	  API (functions mq_*).
+
+	  When POSIX Message Queues are enabled, a directory appears
+	  called /proc/sys/fs/mqueue which can be used to tune kernel
+	  parameters. See mq_overview(7) for details.
+
+	  POSIX Message Queues can also be mounted as a filesystem
+	  called 'mqueue', for example: "mount -t mqueue none /mqueue".
 
 	  If unsure, say Y.
 
 config BSD_PROCESS_ACCT
 	bool "BSD Process Accounting"
 	help
-	  If you say Y here, a user level program will be able to instruct the
-	  kernel (via a special system call) to write process accounting
-	  information to a file: whenever a process exits, information about
-	  that process will be appended to the file by the kernel.  The
-	  information includes things such as creation time, owning user,
-	  command name, memory usage, controlling terminal etc. (the complete
-	  list is in the struct acct in <file:include/linux/acct.h>).  It is
-	  up to the user level program to do useful things with this
-	  information.  This is generally a good idea, so say Y.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Whenever a process exits, information about that process
+	  will be appended to the file. This includes things such as
+	  creation time, owning user, command name, memory usage,
+	  controlling terminal, etc.
+
+	  See sa(1), accton(8) and acct(2) for more details, also
+	  <file:include/linux/acct.h> (struct acct) for the complete
+	  list of stored data.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config BSD_PROCESS_ACCT_V3
 	bool "BSD Process Accounting version 3 file format"
 	depends on BSD_PROCESS_ACCT
 	default n
 	help
-	  If you say Y here, the process accounting information is written
-	  in a new file format that also logs the process IDs of each
-	  process and it's parent. Note that this file format is incompatible
-	  with previous v0/v1/v2 file formats, so you will need updated tools
-	  for processing it. A preliminary version of these tools is available
-	  at <http://www.physik3.uni-rostock.de/tim/kernel/utils/acct/>.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Version 3 is a new file format that also logs the process
+	  ID and process parent ID.
+
+	  Note that this file format is incompatible with previous
+	  v0/v1/v2 file formats, so you will need updated tools
+	  for processing it. One such tool is "bootchart", and
+	  the GNU "acct" package should be able to read the v3
+	  file format too.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config TASKSTATS
 	bool "Export task/process statistics through netlink (EXPERIMENTAL)"

Re: [PATCH 2.6.25-rc2 5/9] Kconfig: Improve init/Kconfig help descriptions - IKCONFIG etc

[Randy Dunlap]

Nick Andrew wrote:
> Rewrite the help descriptions for clarity, accuracy and consistency.
> 
> Kernel config options affected:
> 
>   - IKCONFIG
>   - IKCONFIG_PROC
>   - LOG_BUF_SHIFT

These bits are Acked-by: Randy Dunlap <randy.dunlap@oracle.com>


> Signed-off-by: Nick Andrew <nick@nick-andrew.net>
> ---
> Try #3.
> 
> --- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
> +++ b/init/Kconfig	2008-02-22 09:15:48.000000000 +1100
> @@ -241,20 +241,30 @@ config IKCONFIG
>  	tristate "Kernel .config support"
>  	---help---
>  	  This option enables the complete Linux kernel ".config" file
> -	  contents to be saved in the kernel. It provides documentation
> -	  of which kernel options are used in a running kernel or in an
> -	  on-disk kernel.  This information can be extracted from the kernel
> -	  image file with the script scripts/extract-ikconfig and used as
> -	  input to rebuild the current kernel or to build another kernel.
> -	  It can also be extracted from a running kernel by reading
> -	  /proc/config.gz if enabled (below).
> +	  contents to be saved in the kernel.
> +
> +	  It provides documentation of which kernel options are used in
> +	  a running kernel or in an on-disk kernel.  This information
> +	  can be extracted from the kernel image file with the script
> +	  "scripts/extract-ikconfig" and used as input to rebuild the
> +	  current kernel or to build another kernel.
> +
> +	  It can also be extracted from a running kernel with
> +	  "zcat /proc/config.gz" if CONFIG_IKCONFIG_PROC is enabled
> +	  below.
> +
> +	  Your kernel size will increase by around 14k.
> +
> +	  If unsure, say N.
>  
>  config IKCONFIG_PROC
>  	bool "Enable access to .config through /proc/config.gz"
>  	depends on IKCONFIG && PROC_FS
>  	---help---
> -	  This option enables access to the kernel configuration file
> -	  through /proc/config.gz.
> +	  This option enables access to the configuration of the running
> +	  kernel through /proc/config.gz.
> +
> +	  If unsure, say Y.
>  
>  config LOG_BUF_SHIFT
>  	int "Kernel log buffer size (16 => 64KB, 17 => 128KB)"
> @@ -264,14 +274,15 @@ config LOG_BUF_SHIFT
>  	default 15 if SMP
>  	default 14
>  	help
> -	  Select kernel log buffer size as a power of 2.
> -	  Defaults and Examples:
> +	  Select the kernel log buffer size as a power of 2.
> +
> +	  Defaults and examples:
>  	  	     17 => 128 KB for S/390
> -		     16 => 64 KB for x86 NUMAQ or IA-64
> -	             15 => 32 KB for SMP
> -	             14 => 16 KB for uniprocessor
> -		     13 =>  8 KB
> -		     12 =>  4 KB
> +		     16 =>  64 KB for x86 NUMAQ or IA-64
> +	             15 =>  32 KB for SMP
> +	             14 =>  16 KB for uniprocessor
> +		     13 =>   8 KB
> +		     12 =>   4 KB
>  
>  config CGROUPS
>  	bool "Control Group support"


-- 
~Randy

[PATCH 2.6.25-rc2 1/9] Kconfig: Improve init/Kconfig help descriptions part 1

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

The problems I can see with the supplied help descriptions fall into
these areas:

  - Uses arcane terminology which only kernel developers can understand

  - Inconsistently describes safe response (if unsure, ...)

  - References out-of-date external resources (404 error)

  - Description has not kept pace with recent kernel changes or standards

  - Poor grammar or layout.


My approach to improving the descriptions is to go through each option
checking the correctness of the description, validating any references
it makes, finding inconsistency with the rest of the kernel config,
and trying to improve the usefulness of the explanation. I want to
end up with:

  1 - Single sentence summary of what the option does

  2 - Explain terminology or situation if necessary and possible, linking
  to validated information sources (Documentation directory, manpages,
  scripts, URLs, Wikipedia)

  3 - Suggest safe answer for people who just don't know what to do.


Kernel config options affected:

  - EXPERIMENTAL
  - LOCALVERSION
  - LOCALVERSION_AUTO
  - SWAP
  - SYSVIPC
  - POSIX_MQUEUE
  - BSD_PROCESS_ACCT
  - BSD_PROCESS_ACCT_V3

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-20 09:35:08.000000000 +1100
@@ -20,33 +20,45 @@ menu "General setup"
 config EXPERIMENTAL
 	bool "Prompt for development and/or incomplete code/drivers"
 	---help---
-	  Some of the various things that Linux supports (such as network
-	  drivers, file systems, network protocols, etc.) can be in a state
-	  of development where the functionality, stability, or the level of
-	  testing is not yet high enough for general use. This is usually
-	  known as the "alpha-test" phase among developers. If a feature is
-	  currently in alpha-test, then the developers usually discourage
-	  uninformed widespread use of this feature by the general public to
-	  avoid "Why doesn't this work?" type mail messages. However, active
-	  testing and use of these systems is welcomed. Just be aware that it
-	  may not meet the normal level of reliability or it may fail to work
-	  in some special cases. Detailed bug reports from people familiar
-	  with the kernel internals are usually welcomed by the developers
-	  (before submitting bug reports, please read the documents
-	  <file:README>, <file:MAINTAINERS>, <file:REPORTING-BUGS>,
-	  <file:Documentation/BUG-HUNTING>, and
-	  <file:Documentation/oops-tracing.txt> in the kernel source).
+	  This option enables you to choose kernel configuration
+	  options labeled as EXPERIMENTAL.
+
+	  Some of the various things that Linux supports (such as
+	  network drivers, file systems, network protocols, etc.) can
+	  be in a state of development where the functionality,
+	  stability, or the level of testing is not yet high enough
+	  for general use. This is usually known as the "alpha-test"
+	  phase among developers.
+
+	  If a feature is currently in alpha-test, then the
+	  developers usually discourage uninformed widespread use of
+	  this feature by the general public to avoid "Why doesn't
+	  this work?" type email messages. However, active testing
+	  and use of these systems is welcomed. Just be aware that
+	  it may not meet the normal level of reliability or it
+	  may fail to work in some special cases.
+
+	  Detailed bug reports from people familiar with
+	  the kernel internals are usually welcomed by the
+	  developers. Before submitting bug reports, please
+	  read the documents <file:README>, <file:MAINTAINERS>,
+	  <file:REPORTING-BUGS>, <file:Documentation/BUG-HUNTING>,
+	  and <file:Documentation/oops-tracing.txt> in the kernel
+	  source.
 
 	  This option will also make obsoleted drivers available. These are
 	  drivers that have been replaced by something else, and/or are
 	  scheduled to be removed in a future kernel release.
 
-	  Unless you intend to help test and develop a feature or driver that
-	  falls into this category, or you have a situation that requires
-	  using these features, you should probably say N here, which will
-	  cause the configurator to present you with fewer choices. If
-	  you say Y here, you will be offered the choice of using features or
-	  drivers that are currently considered to be in the alpha-test phase.
+	  Unless you intend to help test and develop a feature or driver
+	  that falls into this category, or you have a situation that
+	  requires using these features, you should probably say N here,
+	  which will cause the configurator to present you with fewer
+	  choices. If you say Y here, you will be offered the choice of
+	  using features or drivers that are currently considered to be
+	  in the alpha-test phase.
+
+	  If unsure, say N.
 
 config BROKEN
 	bool
@@ -74,11 +86,18 @@ config LOCALVERSION
 	string "Local version - append to kernel release"
 	help
 	  Append an extra string to the end of your kernel version.
-	  This will show up when you type uname, for example.
-	  The string you set here will be appended after the contents of
-	  any files with a filename matching localversion* in your
-	  object and source tree, in that order.  Your total string can
-	  be a maximum of 64 characters.
+	  This will show up when you type "uname -r", for example.
+
+	  If you have any files with names matching "localversion*"
+	  in your object or source trees, then the contents of these
+	  files will be appended to your kernel version name.
+
+	  The strings are appended from the object tree files and
+	  then the source tree files, then any string specified
+	  by CONFIG_LOCALVERSION_AUTO below, and finally the value
+	  specified here.
+
+	  The maximum length of a kernel version name is 64 characters.
 
 config LOCALVERSION_AUTO
 	bool "Automatically append version information to the version string"
@@ -93,38 +112,47 @@ config LOCALVERSION_AUTO
 	  appended after any matching localversion* files, and after the value
 	  set in CONFIG_LOCALVERSION.
 
-	  (The actual string used here is the first eight characters produced
+	  The actual string used here is the first eight characters produced
 	  by running the command:
 
 	    $ git rev-parse --verify HEAD
 
-	  which is done within the script "scripts/setlocalversion".)
+	  which is done within the script "scripts/setlocalversion".
 
 config SWAP
 	bool "Support for paging of anonymous memory (swap)"
 	depends on MMU && BLOCK
 	default y
 	help
-	  This option allows you to choose whether you want to have support
-	  for so called swap devices or swap files in your kernel that are
-	  used to provide more virtual memory than the actual RAM present
-	  in your computer.  If unsure say Y.
+	  This option allows you to choose whether you want to have
+	  support for swap devices or swap files in your kernel.
+
+	  Swap is used to provide more virtual memory than the
+	  actual RAM present in your computer. This can improve
+	  performance by moving less frequently used blocks of
+	  memory onto disk, which frees it up for improved disk
+	  caching or active processes.
+
+	  If unsure, say Y.
 
 config SYSVIPC
 	bool "System V IPC"
 	---help---
-	  Inter Process Communication is a suite of library functions and
+	  Inter-Process Communication is a suite of library functions and
 	  system calls which let processes (running programs) synchronize and
 	  exchange information. It is generally considered to be a good thing,
-	  and some programs won't run unless you say Y here. In particular, if
-	  you want to run the DOS emulator dosemu under Linux (read the
-	  DOSEMU-HOWTO, available from <http://www.tldp.org/docs.html#howto>),
-	  you'll need to say Y here.
+	  and some programs won't run without it.
+
+	  In particular, if you want to run the DOS emulator dosemu
+	  under Linux, you'll need to say Y here. You can find out
+	  more about dosemu at <http://dosemu.sourceforge.net/>
 
 	  You can find documentation about IPC with "info ipc" and also in
 	  section 6.4 of the Linux Programmer's Guide, available from
 	  <http://www.tldp.org/guides.html>.
 
+	  If unsure, say Y.
+
 config SYSVIPC_SYSCTL
 	bool
 	depends on SYSVIPC
@@ -135,42 +163,69 @@ config POSIX_MQUEUE
 	bool "POSIX Message Queues"
 	depends on NET && EXPERIMENTAL
 	---help---
-	  POSIX variant of message queues is a part of IPC. In POSIX message
-	  queues every message has a priority which decides about succession
-	  of receiving it by a process. If you want to compile and run
-	  programs written e.g. for Solaris with use of its POSIX message
-	  queues (functions mq_*) say Y here.
-
-	  POSIX message queues are visible as a filesystem called 'mqueue'
-	  and can be mounted somewhere if you want to do filesystem
-	  operations on message queues.
+	  POSIX Message Queues is a type of Inter-Process Communication
+	  (IPC). It provides similar functionality to System V message
+	  queues, with a different Application Programming Interface (API).
+
+	  In POSIX Message Queues, every message has a priority which
+	  determines the order in which each message is delivered to a
+	  receiving process. See mq_overview(7) for details of the
+	  API (functions mq_*).
+
+	  When POSIX Message Queues are enabled, a directory appears
+	  called /proc/sys/fs/mqueue which can be used to tune kernel
+	  parameters. See mq_overview(7) for details.
+
+	  POSIX Message Queues can also be mounted as a filesystem
+	  called 'mqueue', for example: "mount -t mqueue none /mqueue".
 
 	  If unsure, say Y.
 
 config BSD_PROCESS_ACCT
 	bool "BSD Process Accounting"
 	help
-	  If you say Y here, a user level program will be able to instruct the
-	  kernel (via a special system call) to write process accounting
-	  information to a file: whenever a process exits, information about
-	  that process will be appended to the file by the kernel.  The
-	  information includes things such as creation time, owning user,
-	  command name, memory usage, controlling terminal etc. (the complete
-	  list is in the struct acct in <file:include/linux/acct.h>).  It is
-	  up to the user level program to do useful things with this
-	  information.  This is generally a good idea, so say Y.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Whenever a process exits, information about that process
+	  will be appended to the file. This includes things such as
+	  creation time, owning user, command name, memory usage,
+	  controlling terminal, etc.
+
+	  See sa(1), accton(8) and acct(2) for more details, also
+	  <file:include/linux/acct.h> (struct acct) for the complete
+	  list of stored data.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config BSD_PROCESS_ACCT_V3
 	bool "BSD Process Accounting version 3 file format"
 	depends on BSD_PROCESS_ACCT
 	default n
 	help
-	  If you say Y here, the process accounting information is written
-	  in a new file format that also logs the process IDs of each
-	  process and it's parent. Note that this file format is incompatible
-	  with previous v0/v1/v2 file formats, so you will need updated tools
-	  for processing it. A preliminary version of these tools is available
-	  at <http://www.physik3.uni-rostock.de/tim/kernel/utils/acct/>.
+	  BSD Process Accounting enables the kernel to write process
+	  accounting information to a file to track system resources
+	  utilisation and some user actions.
+
+	  Version 3 is a new file format that also logs the process
+	  ID and process parent ID.
+
+	  Note that this file format is incompatible with previous
+	  v0/v1/v2 file formats, so you will need updated tools
+	  for processing it. One such tool is "bootchart", and
+	  the GNU "acct" package should be able to read the v3
+	  file format too.
+
+	  You probably only need this if you have multiple users and
+	  you want to monitor or account for their system usage, and
+	  fine-tune system performance through analysis of the logfile.
+
+	  If unsure, say N.
 
 config TASKSTATS
 	bool "Export task/process statistics through netlink (EXPERIMENTAL)"

[PATCH 2.6.25-rc2 2/9] Kconfig: Improve init/Kconfig help descriptions - TASKSTATS

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - TASKSTATS
  - TASK_DELAY_ACCT
  - TASK_XACCT
  - TASK_IO_ACCOUNTING

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-20 09:35:28.000000000 +1100
@@ -177,42 +177,52 @@ config TASKSTATS
 	depends on NET
 	default n
 	help
-	  Export selected statistics for tasks/processes through the
-	  generic netlink interface. Unlike BSD process accounting, the
-	  statistics are available during the lifetime of tasks/processes as
-	  responses to commands. Like BSD accounting, they are sent to user
-	  space on task exit.
+	  Taskstats is a netlink-based interface for sending per-task
+	  and per-process statistics from the kernel to userspace.
 
-	  Say N if unsure.
+	  Unlike BSD process accounting, the statistics are available
+	  during the lifetime of tasks/processes as responses to
+	  commands. Like BSD accounting, they are sent to user space on
+	  task exit.
+
+	  Netlink is a type of network socket used to transfer data
+	  between the kernel and user space. For more information on
+	  Netlink see <http://qos.ittc.ku.edu/netlink/html/index.html>
+
+	  See <file:Documentation/accounting/taskstats.txt> for more
+	  information on taskstats.
+
+	  If unsure, say N.
 
 config TASK_DELAY_ACCT
 	bool "Enable per-task delay accounting (EXPERIMENTAL)"
 	depends on TASKSTATS
 	help
-	  Collect information on time spent by a task waiting for system
-	  resources like cpu, synchronous block I/O completion and swapping
-	  in pages. Such statistics can help in setting a task's priorities
-	  relative to other tasks for cpu, io, rss limits etc.
+	  Also collect information on time spent by a task waiting for
+	  system resources like CPU, synchronous block I/O completion and
+	  swapping in pages. Such statistics can help in setting a task's
+	  priorities relative to other tasks for CPU, I/O, RSS limits etc.
 
-	  Say N if unsure.
+	  If unsure, say N.
 
 config TASK_XACCT
 	bool "Enable extended accounting over taskstats (EXPERIMENTAL)"
 	depends on TASKSTATS
 	help
-	  Collect extended task accounting data and send the data
-	  to userland for processing over the taskstats interface.
+	  Also collect extended task accounting data and send
+	  the data to userland for processing over the taskstats
+	  interface.
 
-	  Say N if unsure.
+	  If unsure, say N.
 
 config TASK_IO_ACCOUNTING
 	bool "Enable per-task storage I/O accounting (EXPERIMENTAL)"
 	depends on TASK_XACCT
 	help
-	  Collect information on the number of bytes of storage I/O which this
-	  task has caused.
+	  Also collect information on the number of bytes of storage
+	  I/O which this task has caused.
 
-	  Say N if unsure.
+	  If unsure, say N.
 
 config AUDIT
 	bool "Auditing support"

[PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - NAMESPACES
  - UTS_NS
  - IPC_NS
  - USER_NS
  - PID_NS

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-22 09:01:09.000000000 +1100
@@ -414,31 +414,71 @@ config NAMESPACES
 	bool "Namespaces support" if EMBEDDED
 	default !EMBEDDED
 	help
-	  Provides the way to make tasks work with different objects using
-	  the same id. For example same IPC id may refer to different objects
-	  or same user id or pid may refer to different tasks when used in
-	  different namespaces.
+	  Select various namespace options.
+
+	  Namespaces allow different kernel objects (such as processes
+	  or sockets) to have the same ID in different namespaces.
+	  Identifiers like process IDs, which historically were globally
+	  unique, will now be unique only within each PID namespace.
+	  Each task can refer only to PIDs within the same namespace
+	  as the task itself.
+
+	  Namespaces are used by container systems (i.e. vservers)
+	  to provide isolation between the containers.
+
+	  This option does not affect any kernel code directly; it merely
+	  allows you to select namespace options below.
+
+	  Answer Y if you will be using a container system, and you
+	  will probably want to enable all the namespace options
+	  below.
 
 config UTS_NS
 	bool "UTS namespace"
 	depends on NAMESPACES
 	help
-	  In this namespace tasks see different info provided with the
-	  uname() system call
+	  Enable support for multiple UTS system attributes.
+
+	  Each UTS namespace provides an individual view of the
+	  information returned by the uname() system call including
+	  hostname, kernel version and domain name.
+
+	  This is used by container systems (e.g. vservers) so that
+	  each container has its own hostname and other attributes.
+	  Tasks in the container are placed in the UTS namespace
+	  corresponding to the container.
+
+	  Answer Y if you will be using a container system.
 
 config IPC_NS
 	bool "IPC namespace"
 	depends on NAMESPACES && SYSVIPC
 	help
-	  In this namespace tasks work with IPC ids which correspond to
-	  different IPC objects in different namespaces
+	  Enable support for namespace-specific IPC IDs.
+
+	  IPC IDs will be unique only within each IPC namespace.
+
+	  This is used by container systems (e.g. vservers).
+	  Tasks in the container are placed in the IPC namespace
+	  corresponding to the container.
+
+	  Answer Y if you will be using a container system.
 
 config USER_NS
 	bool "User namespace (EXPERIMENTAL)"
 	depends on NAMESPACES && EXPERIMENTAL
 	help
-	  This allows containers, i.e. vservers, to use user namespaces
-	  to provide different user info for different servers.
+	  Enable experimental support for user namespaces.
+
+	  This is a function used by container-based virtualisation systems
+	  (e.g. vservers). User namespaces are intended to ensure that
+	  processes with the same uid which are in different containers are
+	  isolated from each other.
+
+	  Currently user namespaces provide separate accounting, while
+	  isolation must be provided using SELinux or a custom security
+	  module.
+
 	  If unsure, say N.
 
 config PID_NS
@@ -446,12 +486,16 @@ config PID_NS
 	default n
 	depends on NAMESPACES && EXPERIMENTAL
 	help
-	  Suport process id namespaces.  This allows having multiple
-	  process with the same pid as long as they are in different
-	  pid namespaces.  This is a building block of containers.
+	  Enable experimental support for hierarchical process id namespaces.
 
-	  Unless you want to work with an experimental feature
-	  say N here.
+	  This is a function used by container-based virtualisation
+	  systems (e.g. vservers).  Each process will have a distinct
+	  Process ID in each PID namespace which the process is in.
+	  Processes in the container are placed in the PID namespace
+	  corresponding to the container, and cannot see or affect
+	  processes in any parent PID namespace.
+
+	  If unsure, say N.
 
 config BLK_DEV_INITRD
 	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"

[PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

[Nick Andrew]

Modify the help descriptions of init/Kconfig for clarity, accuracy and consistency.

Kernel config options affected:

  - NAMESPACES
  - UTS_NS
  - IPC_NS
  - USER_NS
  - PID_NS

Add a brief description of what namespaces are and when you would
want to use them.

For the *_NS options, add a tiny bit of detail about what it is,
and ensure each config option has an answer hint: Y for namespaces
"if you will be using a container system", Y for the *_NS options
except for the two labeled EXPERIMENTAL.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #4


 init/Kconfig |   65 +++++++++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 50 insertions(+), 15 deletions(-)


diff --git a/init/Kconfig b/init/Kconfig
index cc7a341..0e6a084 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -487,31 +487,62 @@ config NAMESPACES
 	bool "Namespaces support" if EMBEDDED
 	default !EMBEDDED
 	help
-	  Provides the way to make tasks work with different objects using
-	  the same id. For example same IPC id may refer to different objects
-	  or same user id or pid may refer to different tasks when used in
-	  different namespaces.
+	  Select various namespace options.
+
+	  Namespaces allow different kernel objects (such as processes
+	  or sockets) to have the same ID in different namespaces.
+	  Identifiers like process IDs, which historically were globally
+	  unique, will now be unique only within each PID namespace.
+	  Each task can refer only to PIDs within the same namespace
+	  as the task itself.
+
+	  Namespaces are used by container systems (e.g. vservers)
+	  to provide isolation between the containers.
+
+	  This option does not affect any kernel code directly; it merely
+	  allows you to select namespace options below.
+
+	  Answer Y if you will be using a container system, and you
+	  will probably want to enable all the namespace options
+	  below.
 
 config UTS_NS
 	bool "UTS namespace"
 	depends on NAMESPACES
 	help
-	  In this namespace tasks see different info provided with the
-	  uname() system call
+	  Enable support for multiple UTS system attributes.
+
+	  Each UTS namespace provides an individual view of the
+	  information returned by the uname() system call including
+	  hostname, kernel version and domain name.
+
+	  Answer Y if you will be using a container system.
 
 config IPC_NS
 	bool "IPC namespace"
 	depends on NAMESPACES && SYSVIPC
 	help
-	  In this namespace tasks work with IPC ids which correspond to
-	  different IPC objects in different namespaces
+	  Enable support for namespace-specific IPC IDs.
+
+	  IPC IDs will be unique only within each IPC namespace.
+
+	  Answer Y if you will be using a container system.
 
 config USER_NS
 	bool "User namespace (EXPERIMENTAL)"
 	depends on NAMESPACES && EXPERIMENTAL
 	help
-	  This allows containers, i.e. vservers, to use user namespaces
-	  to provide different user info for different servers.
+	  Enable experimental support for user namespaces.
+
+	  This is a function used by container-based virtualisation systems
+	  (e.g. vservers). User namespaces are intended to ensure that
+	  processes with the same uid which are in different containers are
+	  isolated from each other.
+
+	  Currently user namespaces provide separate accounting, while
+	  isolation must be provided using SELinux or a custom security
+	  module.
+
 	  If unsure, say N.
 
 config PID_NS
@@ -519,12 +550,16 @@ config PID_NS
 	default n
 	depends on NAMESPACES && EXPERIMENTAL
 	help
-	  Suport process id namespaces.  This allows having multiple
-	  process with the same pid as long as they are in different
-	  pid namespaces.  This is a building block of containers.
+	  Enable experimental support for hierarchical process id namespaces.
+
+	  This is a function used by container-based virtualisation
+	  systems (e.g. vservers).  Each process will have a distinct
+	  Process ID in each PID namespace which the process is in.
+	  A process can "see" other processes in the same PID namespace
+	  and child PID namespaces, but cannot see processes in parent
+	  PID namespaces.
 
-	  Unless you want to work with an experimental feature
-	  say N here.
+	  If unsure, say N.
 
 config BLK_DEV_INITRD
 	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"

Re: [PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

[Serge E. Hallyn]

Quoting Nick Andrew (nick@nick-andrew.net):
> Modify the help descriptions of init/Kconfig for clarity, accuracy and consistency.
> 
> Kernel config options affected:
> 
>   - NAMESPACES
>   - UTS_NS
>   - IPC_NS
>   - USER_NS
>   - PID_NS
> 
> Add a brief description of what namespaces are and when you would
> want to use them.
> 
> For the *_NS options, add a tiny bit of detail about what it is,
> and ensure each config option has an answer hint: Y for namespaces
> "if you will be using a container system", Y for the *_NS options
> except for the two labeled EXPERIMENTAL.
> 
> Signed-off-by: Nick Andrew <nick@nick-andrew.net>

Thanks, Nick.

Acked-by: Serge Hallyn <serue@us.ibm.com>

-serge

> ---
> Try #4
> 
> 
>  init/Kconfig |   65 +++++++++++++++++++++++++++++++++++++++++++++-------------
>  1 files changed, 50 insertions(+), 15 deletions(-)
> 
> 
> diff --git a/init/Kconfig b/init/Kconfig
> index cc7a341..0e6a084 100644
> --- a/init/Kconfig
> +++ b/init/Kconfig
> @@ -487,31 +487,62 @@ config NAMESPACES
>  	bool "Namespaces support" if EMBEDDED
>  	default !EMBEDDED
>  	help
> -	  Provides the way to make tasks work with different objects using
> -	  the same id. For example same IPC id may refer to different objects
> -	  or same user id or pid may refer to different tasks when used in
> -	  different namespaces.
> +	  Select various namespace options.
> +
> +	  Namespaces allow different kernel objects (such as processes
> +	  or sockets) to have the same ID in different namespaces.
> +	  Identifiers like process IDs, which historically were globally
> +	  unique, will now be unique only within each PID namespace.
> +	  Each task can refer only to PIDs within the same namespace
> +	  as the task itself.
> +
> +	  Namespaces are used by container systems (e.g. vservers)
> +	  to provide isolation between the containers.
> +
> +	  This option does not affect any kernel code directly; it merely
> +	  allows you to select namespace options below.
> +
> +	  Answer Y if you will be using a container system, and you
> +	  will probably want to enable all the namespace options
> +	  below.
> 
>  config UTS_NS
>  	bool "UTS namespace"
>  	depends on NAMESPACES
>  	help
> -	  In this namespace tasks see different info provided with the
> -	  uname() system call
> +	  Enable support for multiple UTS system attributes.
> +
> +	  Each UTS namespace provides an individual view of the
> +	  information returned by the uname() system call including
> +	  hostname, kernel version and domain name.
> +
> +	  Answer Y if you will be using a container system.
> 
>  config IPC_NS
>  	bool "IPC namespace"
>  	depends on NAMESPACES && SYSVIPC
>  	help
> -	  In this namespace tasks work with IPC ids which correspond to
> -	  different IPC objects in different namespaces
> +	  Enable support for namespace-specific IPC IDs.
> +
> +	  IPC IDs will be unique only within each IPC namespace.
> +
> +	  Answer Y if you will be using a container system.
> 
>  config USER_NS
>  	bool "User namespace (EXPERIMENTAL)"
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  This allows containers, i.e. vservers, to use user namespaces
> -	  to provide different user info for different servers.
> +	  Enable experimental support for user namespaces.
> +
> +	  This is a function used by container-based virtualisation systems
> +	  (e.g. vservers). User namespaces are intended to ensure that
> +	  processes with the same uid which are in different containers are
> +	  isolated from each other.
> +
> +	  Currently user namespaces provide separate accounting, while
> +	  isolation must be provided using SELinux or a custom security
> +	  module.
> +
>  	  If unsure, say N.
> 
>  config PID_NS
> @@ -519,12 +550,16 @@ config PID_NS
>  	default n
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  Suport process id namespaces.  This allows having multiple
> -	  process with the same pid as long as they are in different
> -	  pid namespaces.  This is a building block of containers.
> +	  Enable experimental support for hierarchical process id namespaces.
> +
> +	  This is a function used by container-based virtualisation
> +	  systems (e.g. vservers).  Each process will have a distinct
> +	  Process ID in each PID namespace which the process is in.
> +	  A process can "see" other processes in the same PID namespace
> +	  and child PID namespaces, but cannot see processes in parent
> +	  PID namespaces.
> 
> -	  Unless you want to work with an experimental feature
> -	  say N here.
> +	  If unsure, say N.
> 
>  config BLK_DEV_INITRD
>  	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"

[PATCH 2.6.25-rc2 4/9] Kconfig: Improve init/Kconfig help descriptions - AUDIT

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - AUDIT
  - AUDITSYSCALL

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-21 09:15:18.000000000 +1100
@@ -218,20 +218,37 @@ config AUDIT
 	bool "Auditing support"
 	depends on NET
 	help
-	  Enable auditing infrastructure that can be used with another
-	  kernel subsystem, such as SELinux (which requires this for
-	  logging of avc messages output).  Does not do system-call
-	  auditing without CONFIG_AUDITSYSCALL.
+	  Enable an auditing infrastructure that can be used with another
+	  kernel subsystem, such as Security-Enhanced Linux (SELinux),
+	  which requires this option for logging of security related
+	  messages.
+
+	  With this option, the kernel can use netlink to pass audit
+	  messages to an audit daemon process. Otherwise, audit messages
+	  are logged to syslog.
+
+	  See <http://www.nsa.gov/selinux/> for more information
+	  on Security-Enhanced Linux.
+
+	  CONFIG_AUDITSYSCALL (see below) is also required for
+	  system-call auditing.
+
+	  If unsure, say N.
 
 config AUDITSYSCALL
 	bool "Enable system-call auditing support"
 	depends on AUDIT && (X86 || PPC || PPC64 || S390 || IA64 || UML || SPARC64|| SUPERH)
 	default y if SECURITY_SELINUX
 	help
-	  Enable low-overhead system-call auditing infrastructure that
+	  Enable a low-overhead system-call auditing infrastructure that
 	  can be used independently or with another kernel subsystem,
-	  such as SELinux.  To use audit's filesystem watch feature, please
-	  ensure that INOTIFY is configured.
+	  such as SELinux.
+
+	  To use audit's filesystem watch feature, please ensure
+	  that CONFIG_INOTIFY is enabled. See the 'File systems'
+	  menu for Inotify file change notification support.
+
+	  If unsure, say N.
 
 config AUDIT_TREE
 	def_bool y

[PATCH 2.6.25-rc2 5/9] Kconfig: Improve init/Kconfig help descriptions - IKCONFIG etc

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - IKCONFIG
  - IKCONFIG_PROC
  - LOG_BUF_SHIFT
  - SYSFS_DEPRECATED
  - RELAY
  - BLK_DEV_INITRD

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-22 09:15:48.000000000 +1100
@@ -241,20 +241,30 @@ config IKCONFIG
 	tristate "Kernel .config support"
 	---help---
 	  This option enables the complete Linux kernel ".config" file
-	  contents to be saved in the kernel. It provides documentation
-	  of which kernel options are used in a running kernel or in an
-	  on-disk kernel.  This information can be extracted from the kernel
-	  image file with the script scripts/extract-ikconfig and used as
-	  input to rebuild the current kernel or to build another kernel.
-	  It can also be extracted from a running kernel by reading
-	  /proc/config.gz if enabled (below).
+	  contents to be saved in the kernel.
+
+	  It provides documentation of which kernel options are used in
+	  a running kernel or in an on-disk kernel.  This information
+	  can be extracted from the kernel image file with the script
+	  "scripts/extract-ikconfig" and used as input to rebuild the
+	  current kernel or to build another kernel.
+
+	  It can also be extracted from a running kernel with
+	  "zcat /proc/config.gz" if CONFIG_IKCONFIG_PROC is enabled
+	  below.
+
+	  Your kernel size will increase by around 14k.
+
+	  If unsure, say N.
 
 config IKCONFIG_PROC
 	bool "Enable access to .config through /proc/config.gz"
 	depends on IKCONFIG && PROC_FS
 	---help---
-	  This option enables access to the kernel configuration file
-	  through /proc/config.gz.
+	  This option enables access to the configuration of the running
+	  kernel through /proc/config.gz.
+
+	  If unsure, say Y.
 
 config LOG_BUF_SHIFT
 	int "Kernel log buffer size (16 => 64KB, 17 => 128KB)"
@@ -264,14 +274,15 @@ config LOG_BUF_SHIFT
 	default 15 if SMP
 	default 14
 	help
-	  Select kernel log buffer size as a power of 2.
-	  Defaults and Examples:
+	  Select the kernel log buffer size as a power of 2.
+
+	  Defaults and examples:
 	  	     17 => 128 KB for S/390
-		     16 => 64 KB for x86 NUMAQ or IA-64
-	             15 => 32 KB for SMP
-	             14 => 16 KB for uniprocessor
-		     13 =>  8 KB
-		     12 =>  4 KB
+		     16 =>  64 KB for x86 NUMAQ or IA-64
+	             15 =>  32 KB for SMP
+	             14 =>  16 KB for uniprocessor
+		     13 =>   8 KB
+		     12 =>   4 KB
 
 config CGROUPS
 	bool "Control Group support"
@@ -402,11 +413,14 @@ config PROC_PID_CPUSET
 config RELAY
 	bool "Kernel->user space relay support (formerly relayfs)"
 	help
-	  This option enables support for relay interface support in
+	  This option enables support for the relay interface in
 	  certain file systems (such as debugfs).
+
 	  It is designed to provide an efficient mechanism for tools and
 	  facilities to relay large amounts of data from kernel space to
-	  user space.
+	  userspace.
+
+	  See <file:Documentation/filesystems/relay.txt> for more information.
 
 	  If unsure, say N.
 
@@ -457,17 +471,24 @@ config BLK_DEV_INITRD
 	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"
 	depends on BROKEN || !FRV
 	help
+	  Enable use of an initial RAM filesystem or RAM disk at boot
+	  time.
+
 	  The initial RAM filesystem is a ramfs which is loaded by the
-	  boot loader (loadlin or lilo) and that is mounted as root
+	  boot loader (loadlin, lilo, grub) and is mounted as root
 	  before the normal boot procedure. It is typically used to
 	  load modules needed to mount the "real" root file system,
-	  etc. See <file:Documentation/initrd.txt> for details.
+	  etc.
+
+	  For more information, see:
+	  <file:Documentation/initrd.txt>
+	  <file:Documentation/filesystems/ramfs-rootfs-initramfs.txt>
 
 	  If RAM disk support (BLK_DEV_RAM) is also included, this
 	  also enables initial RAM disk (initrd) support and adds
 	  15 Kbytes (more on some other architectures) to the kernel size.
 
-	  If unsure say Y.
+	  If unsure, say Y.
 
 if BLK_DEV_INITRD
 

[PATCH 2.6.25-rc2 6/9] Kconfig: Improve init/Kconfig help descriptions - CGROUPS

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - CGROUPS
  - CGROUP_DEBUG
  - CPUSETS
  - GROUP_SCHED
  - CGROUP_SCHED
  - CGROUP_CPUACCT
  - SYSFS_DEPRECATED
  - CGROUP_MEM_CONT
  - PROC_PID_CPUSET

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-21 08:22:39.000000000 +1100
@@ -276,10 +276,17 @@ config LOG_BUF_SHIFT
 config CGROUPS
 	bool "Control Group support"
 	help
-	  This option will let you use process cgroup subsystems
-	  such as Cpusets
+	  Control Groups enable processes to be grouped into "cgroups"
+	  to facilitate tracking and resource management. For example
+	  a cgroup can tie a set of processes to a set of CPUs using
+	  "cpusets".
 
-	  Say N if unsure.
+	  See <file:Documentation/cgroups.txt> for more information.
+
+	  If you say Y here, you probably want to enable one or
+	  more of the cgroup subsystem options below.
+
+	  If unsure, say N.
 
 config CGROUP_DEBUG
 	bool "Example debug cgroup subsystem"
@@ -287,9 +294,9 @@ config CGROUP_DEBUG
 	help
 	  This option enables a simple cgroup subsystem that
 	  exports useful debugging information about the cgroups
-	  framework
+	  framework.
 
-	  Say N if unsure
+	  If unsure, say N.
 
 config CGROUP_NS
         bool "Namespace cgroup subsystem"
@@ -304,19 +311,24 @@ config CPUSETS
 	bool "Cpuset support"
 	depends on SMP && CGROUPS
 	help
-	  This option will let you create and manage CPUSETs which
+	  This option will let you create and manage "cpusets" which
 	  allow dynamically partitioning a system into sets of CPUs and
 	  Memory Nodes and assigning tasks to run only within those sets.
+
 	  This is primarily useful on large SMP or NUMA systems.
 
-	  Say N if unsure.
+	  See <file:Documentation/cpusets.txt> for more information.
+
+	  If unsure, say N.
 
 config GROUP_SCHED
 	bool "Group CPU scheduler"
 	default y
 	help
-	  This feature lets CPU scheduler recognize task groups and control CPU
-	  bandwidth allocation to such task groups.
+	  This feature enables the CPU scheduler to recognize task groups
+	  and control CPU bandwidth allocation to such task groups.
+
+	  See <file:Documentation/sched-design-CFS.txt> for more information.
 
 config FAIR_GROUP_SCHED
 	bool "Group scheduling for SCHED_OTHER"
@@ -346,9 +358,10 @@ config CGROUP_SCHED
  	help
 	  This option allows you to create arbitrary task groups
 	  using the "cgroup" pseudo filesystem and control
-	  the cpu bandwidth allocated to each such task group.
-	  Refer to Documentation/cgroups.txt for more information
-	  on "cgroup" pseudo filesystem.
+	  the CPU bandwidth allocated to each such task group.
+
+	  See <file:Documentation/cgroups.txt> for more information
+	  on the "cgroup" pseudo filesystem.
 
 endchoice
 
@@ -357,7 +370,7 @@ config CGROUP_CPUACCT
 	depends on CGROUPS
 	help
 	  Provides a simple Resource Controller for monitoring the
-	  total CPU consumed by the tasks in a cgroup
+	  total CPU consumed by the tasks in a cgroup.
 
 config RESOURCE_COUNTERS
 	bool "Resource counters"
@@ -375,6 +388,7 @@ config SYSFS_DEPRECATED
 	  "device"-link, the <subsystem>:<name>-link, and the
 	  "bus"-link. It may also add deprecated key in the
 	  uevent environment.
+
 	  None of these features or values should be used today, as
 	  they export driver core implementation details to userspace
 	  or export properties which can't be kept stable across kernel
@@ -394,10 +408,20 @@ config CGROUP_MEM_CONT
 	  Provides a memory controller that manages both page cache and
 	  RSS memory.
 
+	  If unsure, say N.
+
 config PROC_PID_CPUSET
 	bool "Include legacy /proc/<pid>/cpuset file"
 	depends on CPUSETS
 	default y
+	help
+	  This option provides the /proc/<pid>/cpuset file.
+
+	  This file contains the name of the cpuset in which
+	  the process is executing. For more information, see
+	  <file:Documentation/cpusets.txt>
+
+	  If unsure, say Y.
 
 config RELAY
 	bool "Kernel->user space relay support (formerly relayfs)"

[PATCH 2.6.25-rc2 7/9] Kconfig: Improve init/Kconfig help descriptions - EMBEDDED etc

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - EMBEDDED
  - SYSCTL_SYSCALL
  - KALLSYMS
  - KALLSYMS_ALL
  - KALLSYMS_EXTRA_PASS
  - HOTPLUG
  - PRINTK
  - BUG
  - ELF_CORE
  - BASE_FULL
  - FUTEX
  - EPOLL
  - SIGNALFD
  - TIMERFD
  - EVENTFD

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-20 09:36:28.000000000 +1100
@@ -495,10 +495,14 @@ menuconfig EMBEDDED
 	bool "Configure standard kernel features (for small systems)"
 	help
 	  This option allows certain base kernel options and settings
-          to be disabled or tweaked. This is for specialized
-          environments which can tolerate a "non-standard" kernel.
+	  to be disabled or tweaked. This is for embedded systems and
+	  specialized environments which can tolerate a "non-standard"
+	  kernel.
+
           Only use this if you really know what you are doing.
 
+	  If unsure, say N.
+
 config UID16
 	bool "Enable 16-bit UID system calls" if EMBEDDED
 	depends on ARM || BLACKFIN || CRIS || FRV || H8300 || X86_32 || M68K || (S390 && !64BIT) || SUPERH || SPARC32 || (SPARC64 && SPARC32_COMPAT) || UML || (X86_64 && IA32_EMULATION)
@@ -516,51 +520,62 @@ config SYSCTL_SYSCALL
 	  using paths with ascii names is now the primary path to this
 	  information.
 
-	  Almost nothing using the binary sysctl interface so if you are
+	  Almost nothing uses the binary sysctl interface so if you are
 	  trying to save some space it is probably safe to disable this,
 	  making your kernel marginally smaller.
 
-	  If unsure say Y here.
+	  If unsure, say Y.
 
 config KALLSYMS
-	 bool "Load all symbols for debugging/ksymoops" if EMBEDDED
-	 default y
-	 help
-	   Say Y here to let the kernel print out symbolic crash information and
-	   symbolic stack backtraces. This increases the size of the kernel
-	   somewhat, as all symbols have to be loaded into the kernel image.
+	bool "Load all symbols for debugging/ksymoops" if EMBEDDED
+	default y
+	help
+	  This information causes the kernel to print out symbolic crash
+	  information and symbolic stack backtraces.
+
+	  It increases the size of the kernel somewhat, as all symbols
+	  have to be loaded into the kernel image.
+
+	  If unsure, say Y.
 
 config KALLSYMS_ALL
 	bool "Include all symbols in kallsyms"
 	depends on DEBUG_KERNEL && KALLSYMS
 	help
-	   Normally kallsyms only contains the symbols of functions, for nicer
-	   OOPS messages.  Some debuggers can use kallsyms for other
-	   symbols too: say Y here to include all symbols, if you need them 
-	   and you don't care about adding 300k to the size of your kernel.
+	  Normally kallsyms only contains the symbols of functions, for nicer
+	  OOPS messages.  Some debuggers can use kallsyms for other
+	  symbols too: say Y here to include all symbols, if you need them.
+
+	  Your kernel size will increase by around 300k.
 
-	   Say N.
+	  If unsure, say N.
 
 config KALLSYMS_EXTRA_PASS
 	bool "Do an extra kallsyms pass"
 	depends on KALLSYMS
 	help
-	   If kallsyms is not working correctly, the build will fail with
-	   inconsistent kallsyms data.  If that occurs, log a bug report and
-	   turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
-	   Always say N here unless you find a bug in kallsyms, which must be
-	   reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
-	   you wait for kallsyms to be fixed.
+	  If kallsyms is not working correctly, the build will fail with
+	  inconsistent kallsyms data.  If that occurs, log a bug report and
+	  turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
+
+	  Always say N here unless you find a bug in kallsyms, which must be
+	  reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
+	  you wait for kallsyms to be fixed.
 
+	  If unsure, say N.
 
 config HOTPLUG
 	bool "Support for hot-pluggable devices" if EMBEDDED
 	default y
 	help
 	  This option is provided for the case where no hotplug or uevent
-	  capabilities is wanted by the kernel.  You should only consider
-	  disabling this option for embedded systems that do not use modules, a
-	  dynamic /dev tree, or dynamic device discovery.  Just say Y.
+	  capabilities are wanted by the kernel.
+
+	  You should only consider disabling this option for embedded
+	  systems that do not use modules, a dynamic /dev tree, or
+	  dynamic device discovery.
+
+	  If unsure, say Y.
 
 config PRINTK
 	default y
@@ -572,21 +587,30 @@ config PRINTK
 	  very difficult to diagnose system problems, saying N here is
 	  strongly discouraged.
 
+	  If unsure, say Y.
+
 config BUG
 	bool "BUG() support" if EMBEDDED
 	default y
 	help
           Disabling this option eliminates support for BUG and WARN, reducing
           the size of your kernel image and potentially quietly ignoring
-          numerous fatal conditions. You should only consider disabling this
-          option for embedded systems with no facilities for reporting errors.
-          Just say Y.
+          numerous fatal conditions.
+
+	  You should only consider disabling this option for embedded
+	  systems with no facilities for reporting errors.
+
+	  If unsure, say Y.
 
 config ELF_CORE
 	default y
 	bool "Enable ELF core dumps" if EMBEDDED
 	help
-	  Enable support for generating core dumps. Disabling saves about 4k.
+	  Enable support for generating core dumps when a process fails.
+
+	  Your kernel size will increase by around 4k.
+
+	  If unsure, say Y.
 
 config COMPAT_BRK
 	bool "Disable heap randomization"
@@ -608,6 +632,8 @@ config BASE_FULL
 	  kernel data structures. This saves memory on small machines,
 	  but may reduce performance.
 
+	  If unsure, say Y.
+
 config FUTEX
 	bool "Enable futex support" if EMBEDDED
 	default y
@@ -617,6 +643,8 @@ config FUTEX
 	  support for "fast userspace mutexes".  The resulting kernel may not
 	  run glibc-based applications correctly.
 
+	  If unsure, say Y.
+
 config ANON_INODES
 	bool
 
@@ -628,13 +656,15 @@ config EPOLL
 	  Disabling this option will cause the kernel to be built without
 	  support for epoll family of system calls.
 
+	  If unsure, say Y.
+
 config SIGNALFD
 	bool "Enable signalfd() system call" if EMBEDDED
 	select ANON_INODES
 	default y
 	help
-	  Enable the signalfd() system call that allows to receive signals
-	  on a file descriptor.
+	  Enable the signalfd() system call that allows a process to
+	  receive signals on a file descriptor.
 
 	  If unsure, say Y.
 
@@ -643,8 +673,8 @@ config TIMERFD
 	select ANON_INODES
 	default y
 	help
-	  Enable the timerfd() system call that allows to receive timer
-	  events on a file descriptor.
+	  Enable the timerfd() system call that allows a process to
+	  receive timer events on a file descriptor.
 
 	  If unsure, say Y.
 
@@ -653,8 +683,9 @@ config EVENTFD
 	select ANON_INODES
 	default y
 	help
-	  Enable the eventfd() system call that allows to receive both
-	  kernel notification (ie. KAIO) or userspace notifications.
+	  Enable the eventfd() system call that allows a process to
+	  receive both kernel notification (ie. KAIO) or userspace
+	  notifications.
 
 	  If unsure, say Y.
 

[PATCH 2.6.25-rc2 8/9] Kconfig: Improve init/Kconfig help descriptions - SLAB

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - SLUB_DEBUG
  - SLAB
  - SLUB
  - SLOB

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-20 09:50:54.000000000 +1100
@@ -683,31 +683,48 @@ config SLUB_DEBUG
 	bool "Enable SLUB debugging support" if EMBEDDED
 	depends on SLUB
 	help
+	  Enable debugging on the "SLUB" slab allocator.
+
 	  SLUB has extensive debug support features. Disabling these can
 	  result in significant savings in code size. This also disables
 	  SLUB sysfs support. /sys/slab will not exist and there will be
 	  no support for cache validation etc.
 
+	  If unsure, say N.
+
 choice
 	prompt "Choose SLAB allocator"
 	default SLUB
 	help
-	   This option allows to select a slab allocator.
+	   This option selects a slab allocator.
+
+	   A slab is a contiguous area of kernel memory. Slabs are of
+	   fixed size (1 or more times the page size) and are used as
+	   the container for allocation of kernel data structures. This
+	   reduces memory fragmentation and makes allocation very fast,
+	   improving kernel performance.
+
+	   "SLUB" is the default slab allocator.
+
+	   See wikipedia:Slab_allocation for more details.
 
 config SLAB
 	bool "SLAB"
 	help
-	  The regular slab allocator that is established and known to work
-	  well in all environments. It organizes cache hot objects in
-	  per cpu and per node queues. SLAB is the default choice for
-	  a slab allocator.
+	  SLAB is the original slab allocator that is established and
+	  known to work well in all environments. It organizes cache
+	  hot objects in per-CPU and per-node queues.
+
+	  SLAB has been superseded by SLUB.
 
 config SLUB
 	bool "SLUB (Unqueued Allocator)"
 	help
 	   SLUB is a slab allocator that minimizes cache line usage
-	   instead of managing queues of cached objects (SLAB approach).
-	   Per cpu caching is realized using slabs of objects instead
+	   instead of managing queues of cached objects (the SLAB
+	   approach).
+
+	   Per-CPU caching is realized using slabs of objects instead
 	   of queues of objects. SLUB can use memory efficiently
 	   and has enhanced diagnostics.
 
@@ -715,9 +732,11 @@ config SLOB
 	depends on EMBEDDED
 	bool "SLOB (Simple Allocator)"
 	help
-	   SLOB replaces the stock allocator with a drastically simpler
-	   allocator. SLOB is generally more space efficient but
-	   does not perform as well on large systems.
+	   SLOB is a drastically simpler allocator for use in embedded
+	   systems.
+
+	   SLOB is generally more space efficient but does not perform
+	   as well on large systems.
 
 endchoice
 

[PATCH 2.6.25-rc2 9/9] Kconfig: Improve init/Kconfig help descriptions - MODULES

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - MODULES
  - MODULE_UNLOAD
  - MODULE_FORCE_UNLOAD
  - MODVERSIONS
  - MODULE_SRCVERSION_ALL
  - KMOD

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
---
Try #3.

--- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
+++ b/init/Kconfig	2008-02-22 09:17:11.000000000 +1100
@@ -769,20 +769,26 @@ config BASE_SMALL
 menuconfig MODULES
 	bool "Enable loadable module support"
 	help
-	  Kernel modules are small pieces of compiled code which can
-	  be inserted in the running kernel, rather than being
-	  permanently built into the kernel.  You use the "modprobe"
-	  tool to add (and sometimes remove) them.  If you say Y here,
-	  many parts of the kernel can be built as modules (by
-	  answering M instead of Y where indicated): this is most
-	  useful for infrequently used options which are not required
-	  for booting.  For more information, see the man pages for
-	  modprobe, lsmod, modinfo, insmod and rmmod.
-
-	  If you say Y here, you will need to run "make
-	  modules_install" to put the modules under /lib/modules/
-	  where modprobe can find them (you may need to be root to do
-	  this).
+	  This option allows the kernel to load Kernel modules
+	  at runtime to increase functionality, support new
+	  devices and so on.
+
+	  Kernel modules are compiled code such as device drivers
+	  and filesystems. You can use the "lsmod" command to see
+	  what modules are currently loaded, and "modprobe" to
+	  add (and sometimes remove) them.
+
+	  If you say Y here, many parts of the kernel can be built as
+	  modules (by answering M instead of Y where indicated). This
+	  reduces the size of the compiled kernel and allows you to
+	  choose at runtime which modules will be loaded. With some
+	  other options enabled, module loading and unloading can be
+	  performed automatically by the kernel upon demand.
+
+	  If you say Y here, you will need to run "make modules_install"
+	  after building the kernel to put the modules under /lib/modules/
+	  where "modprobe" can find them. You probably need to be root to
+	  install the modules.
 
 	  If unsure, say Y.
 
@@ -790,10 +796,16 @@ config MODULE_UNLOAD
 	bool "Module unloading"
 	depends on MODULES
 	help
-	  Without this option you will not be able to unload any
-	  modules (note that some modules may not be unloadable
-	  anyway), which makes your kernel slightly smaller and
-	  simpler.  If unsure, say Y.
+	  This option allows the kernel to unload unused modules.
+
+	  A module can only be unloaded if it is not in use by
+	  other modules, the kernel or running processes (for
+	  example, using a device through the module).
+
+	  Disabling this option will make the kernel slightly
+	  smaller and simpler.
+
+	  If unsure, say Y.
 
 config MODULE_FORCE_UNLOAD
 	bool "Forced module unloading"
@@ -803,6 +815,7 @@ config MODULE_FORCE_UNLOAD
 	  kernel believes it is unsafe: the kernel will remove the module
 	  without waiting for anyone to stop using it (using the -f option to
 	  rmmod).  This is mainly for kernel developers and desperate users.
+
 	  If unsure, say N.
 
 config MODVERSIONS
@@ -813,8 +826,9 @@ config MODVERSIONS
 	  Saying Y here makes it sometimes possible to use modules
 	  compiled for different kernels, by adding enough information
 	  to the modules to (hopefully) spot any changes which would
-	  make them incompatible with the kernel you are running.  If
-	  unsure, say N.
+	  make them incompatible with the kernel you are running.
+
+	  If unsure, say N.
 
 config MODULE_SRCVERSION_ALL
 	bool "Source checksum for all modules"
@@ -822,11 +836,15 @@ config MODULE_SRCVERSION_ALL
 	help
 	  Modules which contain a MODULE_VERSION get an extra "srcversion"
 	  field inserted into their modinfo section, which contains a
-    	  sum of the source files which made it.  This helps maintainers
-	  see exactly which source was used to build a module (since
-	  others sometimes change the module source without updating
-	  the version).  With this option, such a "srcversion" field
-	  will be created for all modules.  If unsure, say N.
+	  checksum (using the MD4 algorithm) of the source files which
+	  made it.
+
+	  This helps maintainers see exactly which source was used
+	  to build a module (since others sometimes change the module
+	  source without updating the version).  With this option, such
+	  a "srcversion" field will be created for all modules.
+
+	  If unsure, say N.
 
 config KMOD
 	bool "Automatic kernel module loading"
@@ -834,11 +852,14 @@ config KMOD
 	help
 	  Normally when you have selected some parts of the kernel to
 	  be created as kernel modules, you must load them (using the
-	  "modprobe" command) before you can use them. If you say Y
-	  here, some parts of the kernel will be able to load modules
-	  automatically: when a part of the kernel needs a module, it
-	  runs modprobe with the appropriate arguments, thereby
-	  loading the module if it is available.  If unsure, say Y.
+	  "modprobe" command) before you can use them.
+
+	  If you say Y here, some parts of the kernel will be able to
+	  load modules automatically: when a part of the kernel needs a
+	  module, it will run modprobe with the appropriate arguments,
+	  thereby loading the module if it is available.
+
+	  If unsure, say Y.
 
 config STOP_MACHINE
 	bool

Re: [PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

[Pavel Emelyanov]

Nick Andrew wrote:
> Rewrite the help descriptions for clarity, accuracy and consistency.
> 
> Kernel config options affected:
> 
>   - NAMESPACES
>   - UTS_NS
>   - IPC_NS
>   - USER_NS
>   - PID_NS
> 
> Signed-off-by: Nick Andrew <nick@nick-andrew.net>

Acked-by: Pavel Emelyanov <xemul@openvz.org>

but I also expect the patch for NET_NS soon :)

> ---
> Try #3.
> 
> --- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
> +++ b/init/Kconfig	2008-02-22 09:01:09.000000000 +1100
> @@ -414,31 +414,71 @@ config NAMESPACES
>  	bool "Namespaces support" if EMBEDDED
>  	default !EMBEDDED
>  	help
> -	  Provides the way to make tasks work with different objects using
> -	  the same id. For example same IPC id may refer to different objects
> -	  or same user id or pid may refer to different tasks when used in
> -	  different namespaces.
> +	  Select various namespace options.
> +
> +	  Namespaces allow different kernel objects (such as processes
> +	  or sockets) to have the same ID in different namespaces.
> +	  Identifiers like process IDs, which historically were globally
> +	  unique, will now be unique only within each PID namespace.
> +	  Each task can refer only to PIDs within the same namespace
> +	  as the task itself.
> +
> +	  Namespaces are used by container systems (i.e. vservers)
> +	  to provide isolation between the containers.
> +
> +	  This option does not affect any kernel code directly; it merely
> +	  allows you to select namespace options below.
> +
> +	  Answer Y if you will be using a container system, and you
> +	  will probably want to enable all the namespace options
> +	  below.
>  
>  config UTS_NS
>  	bool "UTS namespace"
>  	depends on NAMESPACES
>  	help
> -	  In this namespace tasks see different info provided with the
> -	  uname() system call
> +	  Enable support for multiple UTS system attributes.
> +
> +	  Each UTS namespace provides an individual view of the
> +	  information returned by the uname() system call including
> +	  hostname, kernel version and domain name.
> +
> +	  This is used by container systems (e.g. vservers) so that
> +	  each container has its own hostname and other attributes.
> +	  Tasks in the container are placed in the UTS namespace
> +	  corresponding to the container.
> +
> +	  Answer Y if you will be using a container system.
>  
>  config IPC_NS
>  	bool "IPC namespace"
>  	depends on NAMESPACES && SYSVIPC
>  	help
> -	  In this namespace tasks work with IPC ids which correspond to
> -	  different IPC objects in different namespaces
> +	  Enable support for namespace-specific IPC IDs.
> +
> +	  IPC IDs will be unique only within each IPC namespace.
> +
> +	  This is used by container systems (e.g. vservers).
> +	  Tasks in the container are placed in the IPC namespace
> +	  corresponding to the container.
> +
> +	  Answer Y if you will be using a container system.
>  
>  config USER_NS
>  	bool "User namespace (EXPERIMENTAL)"
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  This allows containers, i.e. vservers, to use user namespaces
> -	  to provide different user info for different servers.
> +	  Enable experimental support for user namespaces.
> +
> +	  This is a function used by container-based virtualisation systems
> +	  (e.g. vservers). User namespaces are intended to ensure that
> +	  processes with the same uid which are in different containers are
> +	  isolated from each other.
> +
> +	  Currently user namespaces provide separate accounting, while
> +	  isolation must be provided using SELinux or a custom security
> +	  module.
> +
>  	  If unsure, say N.
>  
>  config PID_NS
> @@ -446,12 +486,16 @@ config PID_NS
>  	default n
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  Suport process id namespaces.  This allows having multiple
> -	  process with the same pid as long as they are in different
> -	  pid namespaces.  This is a building block of containers.
> +	  Enable experimental support for hierarchical process id namespaces.
>  
> -	  Unless you want to work with an experimental feature
> -	  say N here.
> +	  This is a function used by container-based virtualisation
> +	  systems (e.g. vservers).  Each process will have a distinct
> +	  Process ID in each PID namespace which the process is in.
> +	  Processes in the container are placed in the PID namespace
> +	  corresponding to the container, and cannot see or affect
> +	  processes in any parent PID namespace.
> +
> +	  If unsure, say N.
>  
>  config BLK_DEV_INITRD
>  	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"
> 

Re: [PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

[Serge E. Hallyn]

Quoting Nick Andrew (nick@nick-andrew.net):
> Rewrite the help descriptions for clarity, accuracy and consistency.
> 
> Kernel config options affected:
> 
>   - NAMESPACES
>   - UTS_NS
>   - IPC_NS
>   - USER_NS
>   - PID_NS
> 
> Signed-off-by: Nick Andrew <nick@nick-andrew.net>
> ---
> Try #3.
> 
> --- a/init/Kconfig	2008-02-20 09:34:48.000000000 +1100
> +++ b/init/Kconfig	2008-02-22 09:01:09.000000000 +1100
> @@ -414,31 +414,71 @@ config NAMESPACES
>  	bool "Namespaces support" if EMBEDDED
>  	default !EMBEDDED
>  	help
> -	  Provides the way to make tasks work with different objects using
> -	  the same id. For example same IPC id may refer to different objects
> -	  or same user id or pid may refer to different tasks when used in
> -	  different namespaces.
> +	  Select various namespace options.
> +
> +	  Namespaces allow different kernel objects (such as processes
> +	  or sockets) to have the same ID in different namespaces.
> +	  Identifiers like process IDs, which historically were globally
> +	  unique, will now be unique only within each PID namespace.
> +	  Each task can refer only to PIDs within the same namespace
> +	  as the task itself.
> +
> +	  Namespaces are used by container systems (i.e. vservers)
> +	  to provide isolation between the containers.
> +
> +	  This option does not affect any kernel code directly; it merely
> +	  allows you to select namespace options below.
> +
> +	  Answer Y if you will be using a container system, and you
> +	  will probably want to enable all the namespace options
> +	  below.
> 
>  config UTS_NS
>  	bool "UTS namespace"
>  	depends on NAMESPACES
>  	help
> -	  In this namespace tasks see different info provided with the
> -	  uname() system call
> +	  Enable support for multiple UTS system attributes.
> +
> +	  Each UTS namespace provides an individual view of the
> +	  information returned by the uname() system call including
> +	  hostname, kernel version and domain name.
> +
> +	  This is used by container systems (e.g. vservers) so that
> +	  each container has its own hostname and other attributes.
> +	  Tasks in the container are placed in the UTS namespace
> +	  corresponding to the container.

Hi Nick,

this paragraph reads a little weird...  really what happens is that
each forked task is in the same UTS namespace as its parent, unless
it was cloned with CLONE_NEWUTS or has done unshare(CLONE_NEWUTS),
in which case it receives a copy.

> +
> +	  Answer Y if you will be using a container system.
> 
>  config IPC_NS
>  	bool "IPC namespace"
>  	depends on NAMESPACES && SYSVIPC
>  	help
> -	  In this namespace tasks work with IPC ids which correspond to
> -	  different IPC objects in different namespaces
> +	  Enable support for namespace-specific IPC IDs.
> +
> +	  IPC IDs will be unique only within each IPC namespace.
> +
> +	  This is used by container systems (e.g. vservers).
> +	  Tasks in the container are placed in the IPC namespace
> +	  corresponding to the container.

Same as with UTS, except that upon CLONE_NEWIPC the task receives a
blank new ipc namespace, not a copy of the original.

> +	  Answer Y if you will be using a container system.
> 
>  config USER_NS
>  	bool "User namespace (EXPERIMENTAL)"
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  This allows containers, i.e. vservers, to use user namespaces
> -	  to provide different user info for different servers.
> +	  Enable experimental support for user namespaces.
> +
> +	  This is a function used by container-based virtualisation systems
> +	  (e.g. vservers). User namespaces are intended to ensure that
> +	  processes with the same uid which are in different containers are
> +	  isolated from each other.
> +
> +	  Currently user namespaces provide separate accounting, while
> +	  isolation must be provided using SELinux or a custom security
> +	  module.
> +
>  	  If unsure, say N.
> 
>  config PID_NS
> @@ -446,12 +486,16 @@ config PID_NS
>  	default n
>  	depends on NAMESPACES && EXPERIMENTAL
>  	help
> -	  Suport process id namespaces.  This allows having multiple
> -	  process with the same pid as long as they are in different
> -	  pid namespaces.  This is a building block of containers.
> +	  Enable experimental support for hierarchical process id namespaces.
> 
> -	  Unless you want to work with an experimental feature
> -	  say N here.
> +	  This is a function used by container-based virtualisation
> +	  systems (e.g. vservers).  Each process will have a distinct
> +	  Process ID in each PID namespace which the process is in.
> +	  Processes in the container are placed in the PID namespace
> +	  corresponding to the container, and cannot see or affect
> +	  processes in any parent PID namespace.

A cloned process inherits the pid namespace hierarchy from its
parent.  If it was cloned with CLONE_NEWPID, the hierarchy is
topped with one additional newly created pid namespace.  This
is the only pid namespace in which the new process will be able
to see processes, while it will be visible in all namespaces in
its pidns hierarchy.

A pid namespace cannot be unshared.

> +
> +	  If unsure, say N.
> 
>  config BLK_DEV_INITRD
>  	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"

Re: [PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

[Nick Andrew]

On Fri, Feb 22, 2008 at 04:14:12PM -0600, Serge E. Hallyn wrote:
> Quoting Nick Andrew (nick@nick-andrew.net):
> >  config UTS_NS
> >  	bool "UTS namespace"
> >  	depends on NAMESPACES
> >  	help
> > -	  In this namespace tasks see different info provided with the
> > -	  uname() system call
> > +	  Enable support for multiple UTS system attributes.
> > +
> > +	  Each UTS namespace provides an individual view of the
> > +	  information returned by the uname() system call including
> > +	  hostname, kernel version and domain name.
> > +
> > +	  This is used by container systems (e.g. vservers) so that
> > +	  each container has its own hostname and other attributes.
> > +	  Tasks in the container are placed in the UTS namespace
> > +	  corresponding to the container.
> 
> this paragraph reads a little weird...  really what happens is that
> each forked task is in the same UTS namespace as its parent, unless
> it was cloned with CLONE_NEWUTS or has done unshare(CLONE_NEWUTS),
> in which case it receives a copy.

You mean only the third paragraph, right? I hope the other two are
accurate.

I'm trying to describe how the feature is used by container systems
and my description is obviously inaccurate. There are subtle semantic
differences between the way the different namespaces work, which you've
pointed out. I think mentioning CLONE_NEWUTS or other flags is too
technical for help descriptions.

For UTS_NS and IPC_NS I think I could remove that paragraph because
the end user hint "Answer Y if you will be using a container system"
remains. For USER_NS and PID_NS however, these features are tagged
EXPERIMENTAL so the hint is "If unsure, say N" and I think I need
to at least mention the use in container systems or find some better
clarifying description which doesn't get too technical.

> > +	  This is used by container systems (e.g. vservers).
> > +	  Tasks in the container are placed in the IPC namespace
> > +	  corresponding to the container.
> 
> Same as with UTS, except that upon CLONE_NEWIPC the task receives a
> blank new ipc namespace, not a copy of the original.

Per above my response is to remove the paragraph.

> >  config PID_NS
> > [...]
> >  	default n
> >  	depends on NAMESPACES && EXPERIMENTAL
> >  	help
> > -	  Suport process id namespaces.  This allows having multiple
> > -	  process with the same pid as long as they are in different
> > -	  pid namespaces.  This is a building block of containers.
> > +	  Enable experimental support for hierarchical process id namespaces.
> > 
> > -	  Unless you want to work with an experimental feature
> > -	  say N here.
> > +	  This is a function used by container-based virtualisation
> > +	  systems (e.g. vservers).  Each process will have a distinct
> > +	  Process ID in each PID namespace which the process is in.
> > +	  Processes in the container are placed in the PID namespace
> > +	  corresponding to the container, and cannot see or affect
> > +	  processes in any parent PID namespace.
> 
> A cloned process inherits the pid namespace hierarchy from its
> parent.  If it was cloned with CLONE_NEWPID, the hierarchy is
> topped with one additional newly created pid namespace.  This
> is the only pid namespace in which the new process will be able
> to see processes, while it will be visible in all namespaces in
> its pidns hierarchy.

Yes, I understand that. Would you agree that your problem is with the
wording "Processes in the container are placed in the PID namespace
corresponding to the container"? And that this is the part that needs
to be fixed?

... todo = revisit these descriptions soon, not today though

Nick.
-- 
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7

Re: [PATCH 2.6.25-rc2 3/9] Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

[Serge E. Hallyn]

Quoting Nick Andrew (nick@nick-andrew.net):
> On Fri, Feb 22, 2008 at 04:14:12PM -0600, Serge E. Hallyn wrote:
> > Quoting Nick Andrew (nick@nick-andrew.net):
> > >  config UTS_NS
> > >  	bool "UTS namespace"
> > >  	depends on NAMESPACES
> > >  	help
> > > -	  In this namespace tasks see different info provided with the
> > > -	  uname() system call
> > > +	  Enable support for multiple UTS system attributes.
> > > +
> > > +	  Each UTS namespace provides an individual view of the
> > > +	  information returned by the uname() system call including
> > > +	  hostname, kernel version and domain name.
> > > +
> > > +	  This is used by container systems (e.g. vservers) so that
> > > +	  each container has its own hostname and other attributes.
> > > +	  Tasks in the container are placed in the UTS namespace
> > > +	  corresponding to the container.
> > 
> > this paragraph reads a little weird...  really what happens is that
> > each forked task is in the same UTS namespace as its parent, unless
> > it was cloned with CLONE_NEWUTS or has done unshare(CLONE_NEWUTS),
> > in which case it receives a copy.
> 
> You mean only the third paragraph, right? I hope the other two are
> accurate.
> 
> I'm trying to describe how the feature is used by container systems
> and my description is obviously inaccurate. There are subtle semantic
> differences between the way the different namespaces work, which you've
> pointed out. I think mentioning CLONE_NEWUTS or other flags is too
> technical for help descriptions.
> 
> For UTS_NS and IPC_NS I think I could remove that paragraph because
> the end user hint "Answer Y if you will be using a container system"
> remains. For USER_NS and PID_NS however, these features are tagged
> EXPERIMENTAL so the hint is "If unsure, say N" and I think I need
> to at least mention the use in container systems or find some better
> clarifying description which doesn't get too technical.
> 
> > > +	  This is used by container systems (e.g. vservers).
> > > +	  Tasks in the container are placed in the IPC namespace
> > > +	  corresponding to the container.
> > 
> > Same as with UTS, except that upon CLONE_NEWIPC the task receives a
> > blank new ipc namespace, not a copy of the original.
> 
> Per above my response is to remove the paragraph.
> 
> > >  config PID_NS
> > > [...]
> > >  	default n
> > >  	depends on NAMESPACES && EXPERIMENTAL
> > >  	help
> > > -	  Suport process id namespaces.  This allows having multiple
> > > -	  process with the same pid as long as they are in different
> > > -	  pid namespaces.  This is a building block of containers.
> > > +	  Enable experimental support for hierarchical process id namespaces.
> > > 
> > > -	  Unless you want to work with an experimental feature
> > > -	  say N here.
> > > +	  This is a function used by container-based virtualisation
> > > +	  systems (e.g. vservers).  Each process will have a distinct
> > > +	  Process ID in each PID namespace which the process is in.
> > > +	  Processes in the container are placed in the PID namespace
> > > +	  corresponding to the container, and cannot see or affect
> > > +	  processes in any parent PID namespace.
> > 
> > A cloned process inherits the pid namespace hierarchy from its
> > parent.  If it was cloned with CLONE_NEWPID, the hierarchy is
> > topped with one additional newly created pid namespace.  This
> > is the only pid namespace in which the new process will be able
> > to see processes, while it will be visible in all namespaces in
> > its pidns hierarchy.
> 
> Yes, I understand that. Would you agree that your problem is with the
> wording "Processes in the container are placed in the PID namespace
> corresponding to the container"? And that this is the part that needs
> to be fixed?

Yup.

thanks,
-serge

> ... todo = revisit these descriptions soon, not today though
> 
> Nick.
> -- 
> PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
> PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7