Skip to contentSkip to conversation

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

PATCH In review Nick Andrew 8 participants 50 messages Feb 19, 2008 – Feb 27, 2008 3 messages not in the archive

lore
Share & tools
lore
#1 lore raw

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

In reply to Nick Andrew
Quoted 9 lines · 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.
[...]
Patch 2
TASKSTATS
TASK_DELAY_ACCT
TASK_XACCT
TASK_IO_ACCOUNTING

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +27 -17
@@ -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)"
#0 lore raw

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.

Signature · 2 lines
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7
#2 lore raw

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

Quoted 5 lines · 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.
[...]
Patch 1

Quoted 8 lines

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.

init/Kconfig +117 -62
@@ -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)"
#3 lore raw

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

In reply to Nick Andrew
Quoted 7 lines · 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.
[...]
Patch 3
USER_NS
PID_NS

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +12 -8
@@ -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"
#16 lore raw

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

In reply to Nick Andrew
Quoted 7 lines · 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.
[...]
Patch 4
AUDIT
AUDITSYSCALL

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +23 -7
@@ -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
#4 lore raw

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

In reply to Nick Andrew
Quoted 8 lines · Nick Andrew
Quoted 7 lines · 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.
[...]
Patch 3
USER_NS
PID_NS

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

Quoted 48 lines

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +12 -9
@@ -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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

#19 lore raw

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

In reply to Nick Andrew
Quoted 11 lines · 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.
[...]
Patch 5
IKCONFIG
IKCONFIG_PROC
LOG_BUF_SHIFT
SYSFS_DEPRECATED
RELAY
BLK_DEV_INITRD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +42 -21
@@ -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
 
#5 lore raw

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

In reply to Pavel Emelyanov
Quoted 10 lines · Pavel Emelyanov
Quoted 8 lines · Nick Andrew
Quoted 7 lines · 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.
[...]
Patch 3
USER_NS
PID_NS

Quoted 2 lines

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.

Signature · 2 lines
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7
#21 lore raw

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

In reply to Nick Andrew
Quoted 4 lines · 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.
[...]

Quoted 8 lines

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.

init/Kconfig +36 -13
@@ -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)"
#30 lore raw

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

In reply to Nick Andrew
Quoted 12 lines · 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.
[...]
Patch 7
EMBEDDED
SYSCTL_SYSCALL
KALLSYMS
KALLSYMS_ALL
KALLSYMS_EXTRA_PASS
HOTPLUG
PRINTK

Quoted 8 lines

BUG
ELF_CORE
BASE_FULL
FUTEX
EPOLL
SIGNALFD
TIMERFD
EVENTFD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +65 -34
@@ -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.
 
#6 lore raw

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

In reply to Nick Andrew
Quoted 13 lines · Nick Andrew
Quoted 11 lines · Pavel Emelyanov
Quoted 8 lines · Nick Andrew
Quoted 7 lines · 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.
[...]
Patch 3
USER_NS
PID_NS

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

Quoted 8 lines

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 :)

Quoted 1 line

Is there any actual documentation on user namespaces and friends?

Hardly :(

Quoted 4 lines

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/

Quoted 10 lines

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 :)

Quoted 1 line

Nick.

#31 lore raw

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

In reply to Nick Andrew
Quoted 9 lines · 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.
[...]
Patch 8
SLUB_DEBUG
SLAB
SLUB
SLOB

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +32 -12
@@ -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
 
#32 lore raw

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

In reply to Nick Andrew
Quoted 11 lines · 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.
[...]
Patch 9
MODULES
MODULE_UNLOAD
MODULE_FORCE_UNLOAD
MODVERSIONS
MODULE_SRCVERSION_ALL
KMOD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +51 -30
@@ -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
#22 lore raw

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

In reply to Nick Andrew

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

init/Kconfig config SYSFS_DEPRECATED · line 408

Quoted 10 lines · Nick Andrew

config PROC_PID_CPUSET

init/Kconfig +6 -0
 	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 ?

Signature · 3 lines
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.940.382.4214
#7 lore raw

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

In reply to Pavel Emelyanov
Quoted 45 lines · Pavel Emelyanov
Quoted 13 lines · Nick Andrew
Quoted 11 lines · Pavel Emelyanov
Quoted 8 lines · Nick Andrew
Quoted 7 lines · 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.
[...]
Patch 3
USER_NS
PID_NS

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

Quoted 8 lines

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 :)

Quoted 1 line

Is there any actual documentation on user namespaces and friends?

Hardly :(

Quoted 4 lines

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/

Quoted 8 lines

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.

Quoted 5 lines
Quoted 2 lines

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.

Quoted 2 lines
Quoted 2 lines

Nick.

thanks,
-serge

#8 lore raw

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

In reply to Pavel Emelyanov
Quoted 19 lines · On Tue, 19 Feb 2008 18:16:53 +0300 Pavel Emelyanov wrote:
Quoted 18 lines · Nick Andrew
Quoted 11 lines · Pavel Emelyanov
Quoted 8 lines · Nick Andrew
Quoted 7 lines · 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.
[...]
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.

Quoted 6 lines
Quoted 3 lines

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

#20 lore raw

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

In reply to Nick Andrew
Quoted 9 lines · On Wed, 20 Feb 2008 01:53:09 +1100 Nick Andrew wrote:
Quoted 8 lines · 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.
[...]
Patch 5
IKCONFIG
IKCONFIG_PROC
LOG_BUF_SHIFT

Those parts are fine. Acked-by: Randy Dunlap <[email protected]>

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

Quoted 62 lines

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

init/Kconfig +22 -14
@@ -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

init/Kconfig config LOG_BUF_SHIFT · line 301

Quoted 10 lines
init/Kconfig +5 -2
-		     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

#9 lore raw

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

In reply to Randy Dunlap
Quoted 2 lines · Randy Dunlap

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.

Signature · 2 lines
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7
#25 lore raw

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

In reply to Nick Andrew

init/Kconfig config LOG_BUF_SHIFT · line 297

Quoted 12 lines · Nick Andrew

config CGROUPS
bool "Control Group support"
help

init/Kconfig +5 -3
-         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

#26 lore raw

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

Quoted 7 lines · Paul Menage

init/Kconfig config LOG_BUF_SHIFT · line 297

Quoted 4 lines · Nick Andrew

config CGROUPS
[...]

init/Kconfig +2 -0
+         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.

#27 lore raw

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

Quoted 12 lines · Nick Andrew

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.

Quoted 7 lines

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.

Quoted 4 lines

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

#17 lore raw

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

In reply to Nick Andrew

init/Kconfig config AUDIT · line 240

Quoted 7 lines · Nick Andrew
init/Kconfig +7 -0
+	  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.. ;)

#10 lore raw

PATCH 3/9 config: Improve init/Kconfig help descriptions - namespaces

In reply to Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- NAMESPACES
- UTS_NS
- IPC_NS
- USER_NS
- PID_NS

---
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.

init/Kconfig +63 -15
@@ -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"
#11 lore raw

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

Quoted 114 lines · Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- NAMESPACES
- UTS_NS
- IPC_NS
- USER_NS
- PID_NS

---
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.

init/Kconfig +51 -15
@@ -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.

init/Kconfig line 500

Quoted 10 lines
init/Kconfig +10 -0
+	  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 :)

Quoted 6 lines
init/Kconfig +2 -0
+
+	  If unsure, say N.
 
 config BLK_DEV_INITRD
 	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"
#23 lore raw

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

In reply to Paul Jackson
Quoted 2 lines · Paul Jackson

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.

#12 lore raw

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

In reply to Pavel Emelyanov
Quoted 8 lines · Pavel Emelyanov

init/Kconfig line 500

Quoted 4 lines
init/Kconfig +4 -0
+	  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.

#13 lore raw

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

Quoted 9 lines · Nick Andrew
Quoted 7 lines · Pavel Emelyanov

init/Kconfig line 500

Quoted 4 lines
init/Kconfig +4 -0
+	  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 :)

Quoted 8 lines

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.

Quoted 2 lines

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.

Quoted 4 lines

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.

Quoted 4 lines

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.

Quoted 2 lines

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

Right.

Quoted 1 line

Process C cannot know where the signal came from.

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

Quoted 5 lines

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.

Quoted 2 lines

Nick.

#24 lore raw

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

In reply to Nick Andrew
Quoted 2 lines · Nick

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

Signature · 3 lines
                  I won't rest till it's the best ...
                  Programmer, Linux Scalability
                  Paul Jackson <[email protected]> 1.940.382.4214
#14 lore raw

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

In reply to Nick Andrew
Quoted 114 lines · Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- NAMESPACES
- UTS_NS
- IPC_NS
- USER_NS
- PID_NS

---
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.

init/Kconfig +51 -15
@@ -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.

init/Kconfig line 500

Quoted 10 lines
init/Kconfig +10 -0
+	  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

Quoted 10 lines
init/Kconfig +2 -1
+
+	  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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

#28 lore raw

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

In reply to Nick Andrew
Quoted 9 lines · Nick Andrew
Quoted 7 lines · Paul Menage

init/Kconfig config LOG_BUF_SHIFT · line 297

Quoted 4 lines · Nick Andrew

config CGROUPS
[...]

init/Kconfig +2 -0
+         When enabled, a new filesystem type "cgroup" is available
+         and can be mounted to control cpusets.

How about:
... cpusets and other resource/behaviour controllers.

Quoted 8 lines

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".

Quoted 24 lines

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 [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

#29 lore raw

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

Quoted 8 lines · On Wed, Feb 20, 2008 at 10:55:07AM -0600, [email protected] wrote:
Quoted 1 line · Nick Andrew

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.

Quoted 3 lines
Quoted 3 lines

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.

#18 lore raw

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

In reply to [email protected]
Quoted 9 lines · On Tue, Feb 19, 2008 at 10:42:10PM -0500, [email protected] wrote:

init/Kconfig config AUDIT · line 240

Quoted 3 lines · Nick Andrew
init/Kconfig +3 -0
+	  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.

Quoted 4 lines

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.

#33 lore raw

PATCH 1/9 init: Improve init/Kconfig help descriptions part 1

In reply to 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

---
Here's try #2 at the 1st patch in the series.
Any comments?

init/Kconfig +117 -62
@@ -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)"
#15 lore raw

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

In reply to [email protected]
Quoted 11 lines · On Wed, Feb 20, 2008 at 10:50:34AM -0600, [email protected] 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.

#35 lore raw

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

In reply to a message not in the archive
Quoted 7 lines · Nick Andrew

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 <[email protected]>

Quoted 69 lines

---
Try #3.

init/Kconfig +27 -16
@@ -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"
Signature · 1 line
~Randy
#36 lore raw

PATCH 1/9 Kconfig: Improve init/Kconfig help descriptions part 1

In reply to 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

---
Try #3.

init/Kconfig +117 -62
@@ -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)"
#37 lore raw

PATCH 2/9 Kconfig: Improve init/Kconfig help descriptions - TASKSTATS

In reply to Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- TASKSTATS
- TASK_DELAY_ACCT
- TASK_XACCT
- TASK_IO_ACCOUNTING

---
Try #3.

init/Kconfig +27 -17
@@ -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"
#38 lore raw

PATCH 3/9 Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

In reply to Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- NAMESPACES
- UTS_NS
- IPC_NS
- USER_NS
- PID_NS

---
Try #3.

init/Kconfig +59 -15
@@ -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"
#41 lore raw

PATCH 4/9 Kconfig: Improve init/Kconfig help descriptions - AUDIT

In reply to Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- AUDIT
- AUDITSYSCALL

---
Try #3.

init/Kconfig +24 -7
@@ -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
#42 lore raw

PATCH 5/9 Kconfig: Improve init/Kconfig help descriptions - IKCONFIG etc

In reply to 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

---
Try #3.

init/Kconfig +42 -21
@@ -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
 
#43 lore raw

PATCH 6/9 Kconfig: Improve init/Kconfig help descriptions - CGROUPS

In reply to 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

---
Try #3.

init/Kconfig +37 -13
@@ -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)"
#44 lore raw

PATCH 7/9 Kconfig: Improve init/Kconfig help descriptions - EMBEDDED etc

In reply to 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

---
Try #3.

init/Kconfig +65 -34
@@ -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.
 
#45 lore raw

PATCH 8/9 Kconfig: Improve init/Kconfig help descriptions - SLAB

In reply to Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- SLUB_DEBUG
- SLAB
- SLUB
- SLOB

---
Try #3.

init/Kconfig +29 -10
@@ -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
 
#46 lore raw

PATCH 9/9 Kconfig: Improve init/Kconfig help descriptions - MODULES

In reply to 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

---
Try #3.

init/Kconfig +51 -30
@@ -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
#48 lore raw

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

In reply to a message not in the archive
Quoted 11 lines · Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- NAMESPACES
- UTS_NS
- IPC_NS
- USER_NS
- PID_NS

but I also expect the patch for NET_NS soon :)

Quoted 110 lines

---
Try #3.

init/Kconfig +59 -15
@@ -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"
#50 lore raw

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

In reply to a message not in the archive
Quoted 49 lines · Nick Andrew

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

- NAMESPACES
- UTS_NS
- IPC_NS
- USER_NS
- PID_NS

---
Try #3.

init/Kconfig +18 -6
@@ -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

init/Kconfig config NAMESPACES · line 449

Quoted 10 lines
init/Kconfig +10 -0
+	  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.

Quoted 6 lines
init/Kconfig +2 -0
+
+	  Answer Y if you will be using a container system.
 
 config IPC_NS
 	bool "IPC namespace"
 	depends on NAMESPACES && SYSVIPC

init/Kconfig config NAMESPACES · line 463

Quoted 10 lines
init/Kconfig +7 -2
 	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.

Quoted 29 lines
init/Kconfig +12 -5
+	  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.

init/Kconfig config PID_NS · line 496

Quoted 10 lines
init/Kconfig +7 -2
+	  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.

Quoted 5 lines
init/Kconfig +2 -0
+
+	  If unsure, say N.
 
 config BLK_DEV_INITRD
 	bool "Initial RAM filesystem and RAM disk (initramfs/initrd) support"
#51 lore raw

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

Quoted 14 lines · Serge E. Hallyn
Quoted 13 lines · Nick Andrew

config UTS_NS

(quoted diff) +7 -2
 	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
Quoted 8 lines

Review

Quoted 3 lines
(quoted diff) +3 -0
+	  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.

Quoted 6 lines

Review

Quoted 3 lines
(quoted diff) +3 -0
+	  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.

Quoted 10 lines
Quoted 10 lines

config PID_NS
[...]

(quoted diff) +1 -3
 	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.
Quoted 15 lines

Review

Quoted 8 lines
(quoted diff) +6 -2
-	  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.

Signature · 2 lines
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7
#52 lore raw

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

Quoted 75 lines · Nick Andrew
Quoted 14 lines · Serge E. Hallyn
Quoted 13 lines · Nick Andrew

config UTS_NS

(quoted diff) +7 -2
 	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
Quoted 8 lines

Review

Quoted 3 lines
(quoted diff) +3 -0
+	  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.

Quoted 6 lines

Review

Quoted 3 lines
(quoted diff) +3 -0
+	  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.

Quoted 10 lines
Quoted 10 lines

config PID_NS
[...]

(quoted diff) +1 -3
 	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.
Quoted 15 lines

Review

Quoted 8 lines
(quoted diff) +6 -2
-	  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.

Quoted 4 lines

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

Quoted 6 lines

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

Nick.

Signature · 2 lines
PGP Key ID = 0x418487E7                      http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7
#39 lore raw

PATCH 3/9 Kconfig: Improve init/Kconfig help descriptions - NAMESPACES

In reply to 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.

---
Try #4

 init/Kconfig |   65 +++++++++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 50 insertions(+), 15 deletions(-)
init/Kconfig +50 -15
index cc7a341..0e6a084 100644
@@ -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"
Acked-by on v1 3/9
#40 lore raw

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

Quoted 13 lines · 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.

Quoted 6 lines

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.

Thanks, Nick.

-serge

Quoted 107 lines

---
Try #4

 init/Kconfig |   65 +++++++++++++++++++++++++++++++++++++++++++++-------------
 1 files changed, 50 insertions(+), 15 deletions(-)
init/Kconfig +50 -15
index cc7a341..0e6a084 100644
@@ -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"