[PATCH try #1] Kconfig: cleanup block/Kconfig.iosched help descriptions

[Nick Andrew]

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

More information is added to each of the I/O scheduler choices and they
are also reordered to improve the flow of information to the user.

IOSCHED_CFQ is the default because it distributes the bandwidth fairly.
It's also the place I decided to add the most help text, because it seems
not possible to add help text to the menu "IO Schedulers" itself.

So IOSCHED_CFQ is annotated with two things. Firstly a hint about how
to use the prioritisation at runtime, i.e. through the ionice(1) command.
Secondly, a reference to Documentation/block/switching-sched.txt to
show how to switch the scheduler for block devices at runtime, and/or
choose a new scheduler via the 'elevator=' kernel parameter.

These schedulers can be compiled as modules (except for noop-iosched)
so this is mentioned in each case. However the Kconfig won't allow a
scheduler which is built as a module to be chosen as the default
scheduler, and I noted that.

The boilerplate "If unsure, say Y" was added to IOSCHED_CFQ, IOSCHED_AS
and IOSCHED_DEADLINE.

A 1-line help description was added to each of the 4 choices under
"Default I/O scheduler". It won't explain anything, but it's friendlier
than saying nothing at all.


Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Questions: Why can't a module be chosen as the default scheduler? The
elevator_get() function in block/elevator.c seems to support it. Is
it that the kernel won't be able to load the module off disk before
it has a scheduler loaded?

Also for people who want to compile only the bare minimum in a kernel
it would seem reasonable to allow IOSCHED_NOOP to be turned off. Is
the lack of a setting here another safety feature? elevator.c certainly
assumes that 'noop' is available:

if (!e) {
e = elevator_get(CONFIG_DEFAULT_IOSCHED);
if (!e) {
printk(KERN_ERR
"Default I/O scheduler not found. " \
"Using noop.\n");
e = elevator_get("noop");
}
}

(note lack of a further test for !e)

Finally my understanding is that USB storage devices, for example,
have constant access time, and so use of an elevator algorithm won't
benefit anything. For these devices why can't the kernel choose "noop"
instead of the default and save the time/space used by the default?


 block/Kconfig.iosched |   74 ++---
 1 files changed, 58 insertions(+), 16 deletions(-)


diff --git a/block/Kconfig.iosched b/block/Kconfig.iosched
index 7e803fc..96a01b3 100644
--- a/block/Kconfig.iosched
+++ b/block/Kconfig.iosched
@@ -2,15 +2,28 @@ if BLOCK
 
 menu "IO Schedulers"
 
-config IOSCHED_NOOP
-   bool
+config IOSCHED_CFQ
+   tristate "CFQ I/O scheduler"
default y
---help---
- The no-op I/O scheduler is a minimal scheduler that does basic merging
- and sorting. Its main uses include non-disk based block devices like
- memory devices, and specialised software or hardware environments
- that do their own scheduling and require only minimal assistance from
- the kernel.
+ The CFQ I/O scheduler tries to distribute bandwidth equally
+ among all processes in the system. It should provide a fair
+ working environment, suitable for desktop systems.
+
+ This is the default I/O scheduler.
+
+ The CFQ I/O scheduler supports prioritisation for individual
+ processes; see ionice(1) for details.
+
+ See  for details
+ on how to choose a default I/O scheduler at boot time and also
+ on a per-device basis at run time.
+
+ To compile this scheduler as a module, choose M here; the module
+ will be called cfq-iosched. A scheduler built as a module cannot
+ be chosen as default.
+
+ If unsure, say Y.
 
 config IOSCHED_AS
tristate "Anticipatory I/O scheduler"
@@ -21,6 +34,15 @@ config IOSCHED_AS
  deadline I/O scheduler, it can also be slower in some cases
  especially some database loads.
 
+ See  for detailed
+ information on this scheduler.
+
+ To compile this scheduler as a module, choose M here; the module
+ will be called as-iosched. A scheduler built as a module cannot
+ be chosen as default.
+
+ If unsure, say Y.
+
 config IOSCHED_DEADLINE
tristate "Deadline I/O scheduler"
default y
@@ -31,14 +53,26 @@ config IOSCHED_DEADLINE
  a disk at any one time, its behaviour is almost identical to the
  anticipatory I/O scheduler and so is a good choice.
 
-config IOSCHED_CFQ
-   tristate "C

Re: [PATCH] More accessible usage of custom flags

[Nick Andrew]

On Sun, Feb 24, 2008 at 04:36:24AM -0500, Nicholas Marquez wrote:
> Yes, I would like to expand them.  If possibly, I'd like to take out
> the individual config options for gcc flags and integrate them into
> the help description.  I feel that the redundancy would not only be
> ugly, but possibly confusing.

If you allow CUSTOM_CFLAGS and friends (as an open-ended set of flags for
the compiler) then yes, having config options like CC_OPTIMIZE_FOR_SIZE
is redundant and should be removed.

Alternately, don't have a CUSTOM_CFLAGS and expand on the set of config
options which set individual compiler flags.  They could be in their
own menu, a bunch of checkboxes to tweak GCC's various optimisation
algorithms and/or warnings. That's certainly going to be friendlier
for the not-very-experienced kernel builder, if less flexible than
CUSTOM_CFLAGS.

> >  I'm hoping we don't need any stern warnings in the kernel configuration.
> >  Although I expect configuring bogus gcc flags is going to break the
> >  build far worse than selecting bad options otherwise. If the user
> >  makes a mistake in CUSTOM_CFLAGS is the build going to fail with
> >  a message "error in CUSTOM_CFLAGS" or is it going to spew out pages
> >  of gcc error messages?  It is nice if error messages can point back
> >  to the source of the error, so the user doesn't have to look through
> >  the entire kernel configuration for what they did wrong.
> 
> I hadn't thought of that.  It would certainly be more useful than a
> stern warning.  ^^;  Have you any ideas on how to implement such a
> thing?  I would imagine a configure-script-like test on the flags to
> make sure that gcc could take them correctly would be in order.  Then
> one could also capture any warnings or errors that gcc outputs (such
> as redundant flags, improper invocation, etc.), fail the build, and
> output the messages.  As far as capturing dangerous flags for the
> kernel (such as -ffast-math or -fmerge-all-constants), there could be
> a blacklist... but that would depend on the gcc version used... :/

I think that's a very interesting idea. Yes, you can test the flags by
compiling and linking a simple program. If it fails, your flags are
bad. You can stop the build right there and say "fix your flags".

The build could also capture the GCC warning/error output and
post-process it. Certain types of warnings might be suppressed,
or cause the build to fail (based on selected config options). My
kernel builds always show a handful of "may be used uninitialised" or
similar ... I just assume that those warnings are harmless. It is best
of course that these warnings don't occur at all, and I expect kernel
developers to fix them when they get a chance.  The idea in this
paragraph would be desirable to me, independent of how the CFLAGS are
specified.


> >  > Something else that could be included is a link to the manual for the
> >  > (currently used) gcc's command flags
> >  > (http://gcc.gnu.org/onlinedocs/gcc-4.2.3/gcc/index.html#toc_Invoking-GCC)
> >  > or at least to the online docs, considering that specifying one
> >  > specific gcc version's manual would yield various issues.
> >
> >  "info gcc" will give all that information in far more detail than I
> >  have time to read.
> 
> I believe you misunderstand.  I mean to include the link in the help
> message.  Like how the links to the appropriate sites for device
> drivers are included in their help messages.

No, I think I understood correctly. If you tell the user to go to that
long URL then you run the risk of pointing to the documentation for a
different version of GCC. On the other hand, if you tell them to type
"info gcc" then they will see the documentation for the version of GCC
which they have installed. And it's also a lot friendlier to write:
"Type 'info gcc' to see a full list of the compiler options".

> >  > I feel that perhaps it is a bit silly to put in such description, as
> >  > one using the flags should only do so in knowing specifically which
> >  > ones they wish to use and why ahead of time.  However, it cannot hurt
> >  > to put in more help documentation, so it's a fine suggestion.
> >
> >  Well, it can't be both silly and a fine suggestion. Does it dumb down
> >  the kernel configuration process too much?
> 
> No, I feel that both adjectives are perfectly reconcilable, at least
> in this case.  Again, more documentation couldn't hurt.  "Dumbing
> down" kernel configuration may be less aesthetically pleasing to
> purists, but that is a tiny price to pay for usability and a widening
> of kernel builders.

I'm looking to find a balance among the competing objectives. Time
will tell with any improvements. I'm also hoping for an aesthetically
pleasing config menu -- perhaps someone else can take on the challenge of
restructuring it to improve the ordering, structure and names of options.

> PS to Nick:  Sorry for the double-send. Didn't CC lkml;  a forward
> would be ugly.

No prob.

Nick.
-- 
PGP Key ID = 0x41

Re: [PATCH] More accessible usage of custom flags

[Nick Andrew]

On Sat, Feb 23, 2008 at 05:28:23PM -0500, Nicholas Marquez wrote:
> First of all, thanks for the input!
> 
> On Sat, Feb 23, 2008 at 5:04 PM, Nick Andrew <[EMAIL PROTECTED]> wrote:
> > On Sat, Feb 23, 2008 at 04:28:50PM -0500, Nicholas Marquez wrote:
>
> There are a few places in the Makefile where options would need to be
> entered.  This just brings those places together in a clean manner and
> allows for one to set the flags via the configuration interface.
> Though it would be excellent if the kernel had more gcc
> micro-optimization (facilitated by such features as the upcoming gcc
> 4.3's -finstrument-functions-exclude-function-list option), general
> CFLAGS used for the entire kernel do not impact the safety of the
> kernel build, assuming that the options are sane.  It would be
> interesting, however, to see an initiative to tune gcc flags for
> important functions and  sections within the kernel for optimal
> performance given some sort of envisioned usage.  (*hint, kernel devs,
> hint*)

If there are some "common" optimisation flags or sets of flags then
maybe they could be turned on/off by invididual config options? There's
already CC_OPTIMIZE_FOR_SIZE sorta tagged as experimental. But then,
enumerating the allowable flags may limit the user's choices whereas I
take it you'd like to expand them.

> >  > >  @@ -487,6 +487,52 @@
> >  > >option.  If problems are observed, a gcc upgrade may be needed.
> >  > >
> >  > >If unsure, say N.
> >  > >  +
> >  > >  +menu "Custom flags"
> >  > >  +
> >  > >  +config CUSTOM_CFLAGS
> >  > >  +string "Custom CFLAGS for kernel"
> >  > >  +default ""
> >  > >  +help
> >  > >  +You can use this to easily set custom gcc CFLAGS to be used 
> > for the
> >  > >  +entire kernel (including modules).
> >  > >  +
> >  > >  +ONLY ADD CUSTOM CFLAGS IF YOU KNOW WHAT YOU ARE DOING
> >  > >  +
> >  > >  +If unsure, leave blank.
> >
> >  Sorry, but I don't think we need shouting. There are a few options
> >  already which have bad results if you unknowingly choose the wrong option,
> >  like enabling EMBEDDED and turning off the BLOCK layer, yet the help
> >  description doesn't shout.
> 
> Sorry about that.  I didn't mean to portray it as "shouting" so much
> as a very visible and stern warning.

I'm hoping we don't need any stern warnings in the kernel configuration.
Although I expect configuring bogus gcc flags is going to break the
build far worse than selecting bad options otherwise. If the user
makes a mistake in CUSTOM_CFLAGS is the build going to fail with
a message "error in CUSTOM_CFLAGS" or is it going to spew out pages
of gcc error messages?  It is nice if error messages can point back
to the source of the error, so the user doesn't have to look through
the entire kernel configuration for what they did wrong.

> Something else that could be included is a link to the manual for the
> (currently used) gcc's command flags
> (http://gcc.gnu.org/onlinedocs/gcc-4.2.3/gcc/index.html#toc_Invoking-GCC)
> or at least to the online docs, considering that specifying one
> specific gcc version's manual would yield various issues.

"info gcc" will give all that information in far more detail than I
have time to read.

> >  The boilerplate "If unsure, leave blank" covers (or is meant to cover)
> >  the situation where the user does not know what they are doing. It says
> >  "If you don't know what you are doing, just leave this field blank,
> >  and everything will be OK" ... except it is put in a non-threatening,
> >  non-demeaning way.
> >
> >  The paragraph in the middle enhances the "help" component of the help
> >  description, by saying why you might want to use that option.
> 
> I feel that perhaps it is a bit silly to put in such description, as
> one using the flags should only do so in knowing specifically which
> ones they wish to use and why ahead of time.  However, it cannot hurt
> to put in more help documentation, so it's a fine suggestion.

Well, it can't be both silly and a fine suggestion. Does it dumb down
the kernel configuration process too much?

I don't want a single person to say "I can't configure this kernel
because I don't know what to answer for the CUSTOM_CFLAGS question"
and I think the "If unsure, leave blank" at the bottom covers that
problem. But I assume you want to encourage experimentation; there
will be a person with a bit higher level of skill who might want
to start tweaking. Here's something they can start tweaking.

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

[PATCH try #1] Kconfig: cleanup block/Kconfig help descriptions

[Nick Andrew]

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

Refactor the BLOCK description a bit. The wording "This permits ... to be
removed" isn't quite right; the block layer is removed when the option
is disabled, whereas most descriptions talk about what happens when the
option is enabled. Reformat the list of what is affected by disabling the
block layer.

Add more examples of large block devices to LBD and strive for technical
accuracy; block devices of size _exactly_ 2TB require CONFIG_LBD,
not only "bigger than 2TB". Also try to say (perhaps not very clearly)
that the config option is only needed when you want to have individual
block devices of size >= 2TB, for example if you had 3 x 1TB disks in
your computer you'd have a total storage size of 3TB but you wouldn't
need the option unless you want to aggregate those disks into a RAID
or LVM.

Improve terminology and grammar on BLK_DEV_IO_TRACE.

I also added the boilerplate "If unsure, say N" to most options.

Precisely say "2TB and larger" for LSF.

Indent the help text for BLK_DEV_BSG by 2 spaces in accordance with
the standard.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
I'm not sure why LSF has "If unsure, say Y." I would have thought it
pretty uncommon to have such large files. Also if you need LSF, you
probably need LBD (can NFS handle 2TB+ files?). Is this a safety
feature? How often is Grandma going to mount a filesystem containing
2TB+ sized files?

Also the description for BLK_DEV_BSG is pretty obscure. Can anybody
suggest why you'd want to do this or what tools you can use or even
some documentation?


 block/Kconfig |   65 +
 1 files changed, 42 insertions(+), 23 deletions(-)


diff --git a/block/Kconfig b/block/Kconfig
index 9bda7bc..a3d8509 100644
--- a/block/Kconfig
+++ b/block/Kconfig
@@ -5,14 +5,18 @@ menuconfig BLOCK
bool "Enable the block layer" if EMBEDDED
default y
help
-This permits the block layer to be removed from the kernel if it's not
-needed (on some embedded devices for example).  If this option is
-disabled, then blockdev files will become unusable and some
-filesystems (such as ext3) will become unavailable.
+Provide block layer support for the kernel.
 
-This option will also disable SCSI character devices and USB storage
-since they make use of various block layer definitions and
-facilities.
+Disable this option to remove the block layer support from the
+kernel. This may be useful for embedded devices.
+
+If this option is disabled:
+
+  - block device files will become unusable
+  - some filesystems (such as ext3) will become unavailable.
+
+Also, SCSI character devices and USB storage will be disabled since
+they make use of various block layer definitions and facilities.
 
 Say Y here unless you know you really don't want to mount disks and
 suchlike.
@@ -23,9 +27,20 @@ config LBD
bool "Support for Large Block Devices"
depends on !64BIT
help
- Say Y here if you want to attach large (bigger than 2TB) discs to
- your machine, or if you want to have a raid or loopback device
- bigger than 2TB.  Otherwise say N.
+ Enable block devices of size 2TB and larger.
+
+ This option is required to support the full capacity of large
+ (2TB+) block devices, including RAID, disk, Network Block Device,
+ Logical Volume Manager (LVM) and loopback.
+
+ For example, RAID devices are frequently bigger than the capacity
+ of the largest individual hard drive.
+
+ This option is not required if you have individual disk drives
+ which total 2TB+ and you are not aggregating the capacity into
+ a large block device (e.g. using RAID or LVM).
+
+ If unsure, say N.
 
 config BLK_DEV_IO_TRACE
bool "Support for tracing block io actions"
@@ -33,19 +48,21 @@ config BLK_DEV_IO_TRACE
select RELAY
select DEBUG_FS
help
- Say Y here, if you want to be able to trace the block layer actions
+ Say Y here if you want to be able to trace the block layer actions
  on a given queue. Tracing allows you to see any traffic happening
- on a block device queue. For more information (and the user space
- support tools needed), fetch the blktrace app from:
+ on a block device queue. For more information (and the userspace
+ support tools needed), fetch the blktrace tools from:
 
  git://brick.kernel.dk/data/git/blktrace.git
 
+ If unsure, say N.
+
 config LSF
bool "Support for Large Single Files"
depends on !64BIT
help
- 

Re: [PATCH] More accessible usage of custom flags

[Nick Andrew]

On Sat, Feb 23, 2008 at 04:28:50PM -0500, Nicholas Marquez wrote:
> Does anyone else have any input on this?  Tips, suggestions, ideas,
> comments, constructive criticism, anything at all.  I am, however,
> trying to avoid a flame war.

I missed it the first time you posted it, so thanks for resending.

> On Sat, Feb 16, 2008 at 9:52 PM, Nicholas Marquez
> <[EMAIL PROTECTED]> wrote:
> > I submitted this patch to the zen-sources Gentoo community and got
> >  much praise and has promptly been included.  This kind of thing have
> >  very likely already been done in other patchsets, but I haven't seen
> >  it around, so I've gone ahead and made one.  The idea is that one can
> >  enable -Os and various other options transparently through standard
> >  kernel configuration, so why bar the builder from any other options to
> >  pass on to gcc (et al)?  One can indeed add one's own flags in the
> >  Makefile, but this method is a good deal friendlier.

Does using this patch reduce the safety of the kernel build at all? i.e.
is it more likely to build different parts of the kernel with
incompatible options with this patch, compared to if the options were
specified in the Makefile?

> >  I see that people who build a Linux kernel are largely of two types:
> >  ~the ones that understand and know enough that they could, with some
> >  nudging and learning, become bonafide kernel devs and
> >  ~the ones that understand it to some very basic degree and can get
> >  through configuring it without too much trouble (though with limited
> >  understanding)

I'm currently cleaning up the Kconfig help descriptions to try to help
the second group of people. Also I think there's a spectrum of
capabilities involved. I'd like kernel building to be a fun and useful
activity for a wider group of people :-)

> >  Whilst all other kernel devs are hacking away
> >  at the rough and tumultuous innards of the kernel, a few people of
> >  less confidence and experience (people like me) could polish the
> >  outside to make it more appealing to more people.

Heh, that includes me too.

> >  __
> >  diff -dur original/init/Kconfig modified/init/Kconfig
> >  --- original/init/Kconfig2008-02-16 20:24:22.0 -0500
> >  +++ modified/init/Kconfig2008-02-16 20:53:48.0 -0500

I've just started using StGit and it makes it a lot easier to make, send
and manage patches. You should take a look at it.

> >  @@ -487,6 +487,52 @@
> >option.  If problems are observed, a gcc upgrade may be needed.
> >
> >If unsure, say N.
> >  +
> >  +menu "Custom flags"
> >  +
> >  +config CUSTOM_CFLAGS
> >  +string "Custom CFLAGS for kernel"
> >  +default ""
> >  +help
> >  +You can use this to easily set custom gcc CFLAGS to be used for 
> > the
> >  +entire kernel (including modules).
> >  +
> >  +ONLY ADD CUSTOM CFLAGS IF YOU KNOW WHAT YOU ARE DOING
> >  +
> >  +If unsure, leave blank.

Sorry, but I don't think we need shouting. There are a few options
already which have bad results if you unknowingly choose the wrong option,
like enabling EMBEDDED and turning off the BLOCK layer, yet the help
description doesn't shout.

Can I suggest:

help
  You can use this to easily set custom gcc CFLAGS to be used
  for the entire kernel build process (including modules).

  Compiler flags can be used for increasing or reducing
  optimisation, enabling debugging, cross compilation
  and so on.

  If unsure, leave blank.

The boilerplate "If unsure, leave blank" covers (or is meant to cover)
the situation where the user does not know what they are doing. It says
"If you don't know what you are doing, just leave this field blank,
and everything will be OK" ... except it is put in a non-threatening,
non-demeaning way.

The paragraph in the middle enhances the "help" component of the help
description, by saying why you might want to use that option.

> >  +config CUSTOM_LDFLAGS
> >  [...]
> >  +config CUSTOM_AFLAGS
> >  [...]
> >  +config CUSTOM_MAKEFLAGS
> >  [...]

Similar comments apply.

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

[PATCH spelling] Tighten up the use of loose

[Nick Andrew]

'Lose' is when you don't win or you've lost something, and 'loose'
is when something isn't tight. I just want to tighten up the
spelling a bit regarding some loose comments.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Yes, this is a digression.


 Documentation/edac.txt  |2 +-
 Documentation/filesystems/hfs.txt   |2 +-
 arch/mips/kernel/vpe.c  |2 +-
 arch/sh/lib64/c-checksum.c  |4 ++--
 drivers/char/serial167.c|2 +-
 drivers/media/dvb/ttpci/av7110.c|2 +-
 drivers/message/i2o/i2o_block.c |2 +-
 drivers/misc/ibmasm/event.c |2 +-
 drivers/net/spider_net.c|2 +-
 drivers/serial/mpc52xx_uart.c   |4 ++--
 drivers/usb/serial/ftdi_sio.c   |2 +-
 fs/jffs2/fs.c   |2 +-
 fs/ntfs/aops.c  |2 +-
 include/linux/securebits.h  |2 +-
 mm/migrate.c|2 +-
 mm/slub.c   |4 ++--
 net/ieee80211/softmac/ieee80211softmac_module.c |2 +-
 net/wireless/wext.c |2 +-
 18 files changed, 21 insertions(+), 21 deletions(-)


diff --git a/Documentation/edac.txt b/Documentation/edac.txt
index a5c3684..bad5fef 100644
--- a/Documentation/edac.txt
+++ b/Documentation/edac.txt
@@ -280,7 +280,7 @@ Polling period control file:
 
The time period, in milliseconds, for polling for error information.
Too small a value wastes resources.  Too large a value might delay
-   necessary handling of errors and might loose valuable information for
+   necessary handling of errors and might lose valuable information for
locating the error.  1000 milliseconds (once each second) is the current
default. Systems which require all the bandwidth they can get, may
increase this.
diff --git a/Documentation/filesystems/hfs.txt 
b/Documentation/filesystems/hfs.txt
index bd0fa77..28f0225 100644
--- a/Documentation/filesystems/hfs.txt
+++ b/Documentation/filesystems/hfs.txt
@@ -61,7 +61,7 @@ the a little strange:
Finder's metadata.
  o They are however created (with default values), deleted and renamed
along with the corresponding data fork or directory.
- o Copying files to a different filesystem will loose those attributes
+ o Copying files to a different filesystem will lose those attributes
that are essential for MacOS to work.
 
 
diff --git a/arch/mips/kernel/vpe.c b/arch/mips/kernel/vpe.c
index eed2dc4..c6cf1ae 100644
--- a/arch/mips/kernel/vpe.c
+++ b/arch/mips/kernel/vpe.c
@@ -1112,7 +1112,7 @@ static int vpe_release(struct inode *inode, struct file 
*filp)
 
/* It's good to be able to run the SP and if it chokes have a look at
   the /dev/rt?. But if we reset the pointer to the shared struct we
-  loose what has happened. So perhaps if garbage is sent to the vpe
+  lose what has happened. So perhaps if garbage is sent to the vpe
   device, use it as a trigger for the reset. Hopefully a nice
   executable will be along shortly. */
if (ret < 0)
diff --git a/arch/sh/lib64/c-checksum.c b/arch/sh/lib64/c-checksum.c
index 5dfbd8b..83d0776 100644
--- a/arch/sh/lib64/c-checksum.c
+++ b/arch/sh/lib64/c-checksum.c
@@ -35,7 +35,7 @@ static inline unsigned short foldto16(unsigned long x)
 
 static inline unsigned short myfoldto16(unsigned long long x)
 {
-   /* Fold down to 32-bits so we don't loose in the typedef-less
+   /* Fold down to 32-bits so we don't lose in the typedef-less
   network stack.  */
/* 64 to 33 */
x = (x & 0x) + (x >> 32);
@@ -199,7 +199,7 @@ __wsum csum_tcpudp_nofold(__be32 saddr, __be32 daddr,
result = (__force u64) saddr + (__force u64) daddr +
 (__force u64) sum + ((len + proto) << 8);
 
-   /* Fold down to 32-bits so we don't loose in the typedef-less
+   /* Fold down to 32-bits so we don't lose in the typedef-less
   network stack.  */
/* 64 to 33 */
result = (result & 0x) + (result >> 32);
diff --git a/drivers/char/serial167.c b/drivers/char/serial167.c
index df8cd0c..201eb83 100644
--- a/drivers/char/serial167.c
+++ b/drivers/char/serial167.c
@@ -418,7 +418,7 @@ static irqreturn_t cd2401_rxerr_interrupt(int irq, void 
*dev_id)
 TTY_OVERRUN);
/*
   If the flip buffer itself is
-  overflowing, we still loose
+   

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

[Nick Andrew]

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

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

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

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

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

Per above my response is to remove the paragraph.

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

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

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

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

[PATCH try #1] Kconfig: cleanup usr/Kconfig help descriptions

[Nick Andrew]

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

This patch mostly clarifies what INITRAMFS_SOURCE does, i.e. optionally
build a CPIO archive of the initial root filesystem (initramfs) and
compress it and link it into the kernel.  Note that usually the initramfs
is separate, and loaded by a bootloader (and I give a list of the common
ones, for clarity).

Correct the filename of gen_init_cpio.c and clarify that any filenames
specified contain lists of directives for the archive builder, rather than
files to be added directly into the archive.

Improve grammar on INITRAMFS_ROOT_UID and INITRAMFS_ROOT_GID and
use consistent terminology.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
I think I might be starting to get the hang of this :-)


 usr/Kconfig |   51 +--
 1 files changed, 33 insertions(+), 18 deletions(-)


diff --git a/usr/Kconfig b/usr/Kconfig
index 86cecb5..0ad8713 100644
--- a/usr/Kconfig
+++ b/usr/Kconfig
@@ -6,41 +6,56 @@ config INITRAMFS_SOURCE
string "Initramfs source file(s)"
default ""
help
- This can be either a single cpio archive with a .cpio suffix or a
- space-separated list of directories and files for building the
- initramfs image.  A cpio archive should contain a filesystem archive
- to be used as an initramfs image.  Directories should contain a
- filesystem layout to be included in the initramfs image.  Files
- should contain entries according to the format described by the
- "usr/gen_init_cpio" program in the kernel tree.
+ Specify the contents of an early userspace image to be linked
+ into the kernel image.
+
+ A booting kernel usually obtains an initramfs image from a
+ bootloader (e.g. loadlin, lilo or grub). Alternately one can
+ be built and linked into the kernel image using this option.
+
+ You can specify either a single cpio archive filename with a .cpio
+ suffix or a space-separated list of directories and files for
+ building the initramfs image. The result will be a compressed
+ cpio archive containing a filesystem layout which will be
+ used as an initramfs image by the booting kernel.
+
+ A cpio archive should contain a filesystem layout which will
+ become the initramfs image.
+
+ Directories should contain a filesystem layout to be included
+ into the initramfs image.
+
+ Files should contain a list of directives according to the
+ format described by the  program in
+ the kernel tree.
 
  When multiple directories and files are specified then the
  initramfs image will be the aggregate of all of them.
 
  See  for more details.
 
- If you are not sure, leave it blank.
+ If unsure, leave it blank.
 
 config INITRAMFS_ROOT_UID
int "User ID to map to 0 (user root)"
depends on INITRAMFS_SOURCE!=""
default "0"
help
- This setting is only meaningful if the INITRAMFS_SOURCE is
- contains a directory.  Setting this user ID (UID) to something
- other than "0" will cause all files owned by that UID to be
- owned by user root in the initial ramdisk image.
+ This setting is only meaningful if INITRAMFS_SOURCE contains
+ a directory.  Setting this user ID (UID) to something other
+ than "0" will cause all files owned by that UID in the source
+ directories to be owned by user root in the initramfs image.
 
- If you are not sure, leave it set to "0".
+ If unsure, leave it set to "0".
 
 config INITRAMFS_ROOT_GID
int "Group ID to map to 0 (group root)"
depends on INITRAMFS_SOURCE!=""
default "0"
help
- This setting is only meaningful if the INITRAMFS_SOURCE is
- contains a directory.  Setting this group ID (GID) to something
- other than "0" will cause all files owned by that GID to be
- owned by group root in the initial ramdisk image.
+ This setting is only meaningful if INITRAMFS_SOURCE contains
+ a directory.  Setting this group ID (GID) to something other
+ than "0" will cause all files owned by that GID in the source
+ directories to be owned by group root in the initramfs image.
 
- If you are not sure, leave it set to "0".
+ If unsure, leave it set to "0".

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

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

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

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

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

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - SLUB_DEBUG
  - SLAB
  - SLUB
  - SLOB

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

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

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

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

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

--- a/init/Kconfig  2008-02-20 09:34:48.0 +1100
+++ b/init/Kconfig  2008-02-20 09:36:28.0 +1100
@@ -495,10 +495,14 @@ menuconfig EMBEDDED
bool "Configure standard kernel features (for small systems)"
help
  This option allows certain base kernel options and settings
-  to be disabled or tweaked. This is for specialized
-  environments which can tolerate a "non-standard" kernel.
+ to be disabled or tweaked. This is for embedded systems and
+ specialized environments which can tolerate a "non-standard"
+ kernel.
+
   Only use this if you really know what you are doing.
 
+ If unsure, say N.
+
 config UID16
bool "Enable 16-bit UID system calls" if EMBEDDED
depends on ARM || BLACKFIN || CRIS || FRV || H8300 || X86_32 || M68K || 
(S390 && !64BIT) || SUPERH || SPARC32 || (SPARC64 && SPARC32_COMPAT) || UML || 
(X86_64 && IA32_EMULATION)
@@ -516,51 +520,62 @@ config SYSCTL_SYSCALL
  using paths with ascii names is now the primary path to this
  information.
 
- Almost nothing using the binary sysctl interface so if you are
+ Almost nothing uses the binary sysctl interface so if you are
  trying to save some space it is probably safe to disable this,
  making your kernel marginally smaller.
 
- If unsure say Y here.
+ If unsure, say Y.
 
 config KALLSYMS
-bool "Load all symbols for debugging/ksymoops" if EMBEDDED
-default y
-help
-  Say Y here to let the kernel print out symbolic crash information and
-  symbolic stack backtraces. This increases the size of the kernel
-  somewhat, as all symbols have to be loaded into the kernel image.
+   bool "Load all symbols for debugging/ksymoops" if EMBEDDED
+   default y
+   help
+ This information causes the kernel to print out symbolic crash
+ information and symbolic stack backtraces.
+
+ It increases the size of the kernel somewhat, as all symbols
+ have to be loaded into the kernel image.
+
+ If unsure, say Y.
 
 config KALLSYMS_ALL
bool "Include all symbols in kallsyms"
depends on DEBUG_KERNEL && KALLSYMS
help
-  Normally kallsyms only contains the symbols of functions, for nicer
-  OOPS messages.  Some debuggers can use kallsyms for other
-  symbols too: say Y here to include all symbols, if you need them 
-  and you don't care about adding 300k to the size of your kernel.
+ Normally kallsyms only contains the symbols of functions, for nicer
+ OOPS messages.  Some debuggers can use kallsyms for other
+ symbols too: say Y here to include all symbols, if you need them.
+
+ Your kernel size will increase by around 300k.
 
-  Say N.
+ If unsure, say N.
 
 config KALLSYMS_EXTRA_PASS
bool "Do an extra kallsyms pass"
depends on KALLSYMS
help
-  If kallsyms is not working correctly, the build will fail with
-  inconsistent kallsyms data.  If that occurs, log a bug report and
-  turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
-  Always say N here unless you find a bug in kallsyms, which must be
-  reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
-  you wait for kallsyms to be fixed.
+ If kallsyms is not working correctly, the build will fail with
+ inconsistent kallsyms data.  If that occurs, log a bug report and
+ turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
+
+ Always say N here unless you find a bug in kallsyms, which must be
+ reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
+ you wait for kallsyms to be fixed.
 
+ If unsure, say N.
 
 config HOTPLUG
bool "Support for hot-pluggable devices" if EMBEDDED
default y
help
  This option is provided for the case where no hotplug or uevent
- capabilities is wanted by the kernel.  You should only consider
- disabling this option for embedded systems that do not use modules, a
- dynamic /dev tree, or dynamic device discovery.  Just say Y.
+ capabilities are wanted by the kernel.
+
+ You should only consider disabling this option for embedded
+ systems that do not use modules, a 

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

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

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

--- a/init/Kconfig  2008-02-20 09:34:48.0 +1100
+++ b/init/Kconfig  2008-02-21 08:22:39.0 +1100
@@ -276,10 +276,17 @@ config LOG_BUF_SHIFT
 config CGROUPS
bool "Control Group support"
help
- This option will let you use process cgroup subsystems
- such as Cpusets
+ Control Groups enable processes to be grouped into "cgroups"
+ to facilitate tracking and resource management. For example
+ a cgroup can tie a set of processes to a set of CPUs using
+ "cpusets".
 
- Say N if unsure.
+ See  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  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  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  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 :-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//cpuset file"
depends on CPUSETS
default y
+   help
+ This option provides the /proc//cpuset file.
+
+ This file contains the name of the cpuset in which
+ the process is executing. For more information, see
+ 
+
+ If unsure, say Y.
 
 config RELAY
bool "Kernel->user space relay support (formerly relayfs)"
--
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/

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

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

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

--- a/init/Kconfig  2008-02-20 09:34:48.0 +1100
+++ b/init/Kconfig  2008-02-22 09:15:48.0 +1100
@@ -241,20 +241,30 @@ config IKCONFIG
tristate "Kernel .config support"
---help---
  This option enables the complete Linux kernel ".config" file
- contents to be saved in the kernel. It provides documentation
- of which kernel options are used in a running kernel or in an
- on-disk kernel.  This information can be extracted from the kernel
- image file with the script scripts/extract-ikconfig and used as
- input to rebuild the current kernel or to build another kernel.
- It can also be extracted from a running kernel by reading
- /proc/config.gz if enabled (below).
+ contents to be saved in the kernel.
+
+ It provides documentation of which kernel options are used in
+ a running kernel or in an on-disk kernel.  This information
+ can be extracted from the kernel image file with the script
+ "scripts/extract-ikconfig" and used as input to rebuild the
+ current kernel or to build another kernel.
+
+ It can also be extracted from a running kernel with
+ "zcat /proc/config.gz" if CONFIG_IKCONFIG_PROC is enabled
+ below.
+
+ Your kernel size will increase by around 14k.
+
+ If unsure, say N.
 
 config IKCONFIG_PROC
bool "Enable access to .config through /proc/config.gz"
depends on IKCONFIG && PROC_FS
---help---
- This option enables access to the kernel configuration file
- through /proc/config.gz.
+ This option enables access to the configuration of the running
+ kernel through /proc/config.gz.
+
+ If unsure, say Y.
 
 config LOG_BUF_SHIFT
int "Kernel log buffer size (16 => 64KB, 17 => 128KB)"
@@ -264,14 +274,15 @@ config LOG_BUF_SHIFT
default 15 if SMP
default 14
help
- Select kernel log buffer size as a power of 2.
- Defaults and Examples:
+ Select the kernel log buffer size as a power of 2.
+
+ Defaults and examples:
 17 => 128 KB for S/390
-16 => 64 KB for x86 NUMAQ or IA-64
-15 => 32 KB for SMP
-14 => 16 KB for uniprocessor
-13 =>  8 KB
-12 =>  4 KB
+16 =>  64 KB for x86 NUMAQ or IA-64
+15 =>  32 KB for SMP
+14 =>  16 KB for uniprocessor
+13 =>   8 KB
+12 =>   4 KB
 
 config CGROUPS
bool "Control Group support"
@@ -402,11 +413,14 @@ config PROC_PID_CPUSET
 config RELAY
bool "Kernel->user space relay support (formerly relayfs)"
help
- This option enables support for relay interface support in
+ This option enables support for the relay interface in
  certain file systems (such as debugfs).
+
  It is designed to provide an efficient mechanism for tools and
  facilities to relay large amounts of data from kernel space to
- user space.
+ userspace.
+
+ See  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  for details.
+ etc.
+
+ For more information, see:
+ 
+ 
 
  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
 
--
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/

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - AUDIT
  - AUDITSYSCALL

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

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

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - NAMESPACES
  - UTS_NS
  - IPC_NS
  - USER_NS
  - PID_NS

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

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

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

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

  - Uses arcane terminology which only kernel developers can understand

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

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

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

  - Poor grammar or layout.


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

  1 - Single sentence summary of what the option does

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

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


Kernel config options affected:

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

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

--- a/init/Kconfig  2008-02-20 09:34:48.0 +1100
+++ b/init/Kconfig  2008-02-20 09:35:08.0 +1100
@@ -20,33 +20,45 @@ menu "General setup"
 config EXPERIMENTAL
bool "Prompt for development and/or incomplete code/drivers"
---help---
- Some of the various things that Linux supports (such as network
- drivers, file systems, network protocols, etc.) can be in a state
- of development where the functionality, stability, or the level of
- testing is not yet high enough for general use. This is usually
- known as the "alpha-test" phase among developers. If a feature is
- currently in alpha-test, then the developers usually discourage
- uninformed widespread use of this feature by the general public to
- avoid "Why doesn't this work?" type mail messages. However, active
- testing and use of these systems is welcomed. Just be aware that it
- may not meet the normal level of reliability or it may fail to work
- in some special cases. Detailed bug reports from people familiar
- with the kernel internals are usually welcomed by the developers
- (before submitting bug reports, please read the documents
- , , ,
- , and
-  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 , ,
+ , ,
+ and  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-

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - TASKSTATS
  - TASK_DELAY_ACCT
  - TASK_XACCT
  - TASK_IO_ACCOUNTING

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Try #3.

--- a/init/Kconfig  2008-02-20 09:34:48.0 +1100
+++ b/init/Kconfig  2008-02-20 09:35:28.0 +1100
@@ -177,42 +177,52 @@ config TASKSTATS
depends on NET
default n
help
- Export selected statistics for tasks/processes through the
- generic netlink interface. Unlike BSD process accounting, the
- statistics are available during the lifetime of tasks/processes as
- responses to commands. Like BSD accounting, they are sent to user
- space on task exit.
+ Taskstats is a netlink-based interface for sending per-task
+ and per-process statistics from the kernel to userspace.
 
- Say N if unsure.
+ Unlike BSD process accounting, the statistics are available
+ during the lifetime of tasks/processes as responses to
+ commands. Like BSD accounting, they are sent to user space on
+ task exit.
+
+ Netlink is a type of network socket used to transfer data
+ between the kernel and user space. For more information on
+ Netlink see <http://qos.ittc.ku.edu/netlink/html/index.html>
+
+ See  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"
--
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/

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

[Nick Andrew]

On Wed, Feb 20, 2008 at 10:50:34AM -0600, [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.
--
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/

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

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

  - Uses arcane terminology which only kernel developers can understand

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

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

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

  - Poor grammar or layout.


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

  1 - Single sentence summary of what the option does

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

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


Kernel config options affected:

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

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
---
Here's try #2 at the 1st patch in the series.
Any comments?


--- a/init/Kconfig  2008-02-20 09:34:48.0 +1100
+++ b/init/Kconfig  2008-02-20 09:35:08.0 +1100
@@ -20,33 +20,45 @@ menu "General setup"
 config EXPERIMENTAL
bool "Prompt for development and/or incomplete code/drivers"
---help---
- Some of the various things that Linux supports (such as network
- drivers, file systems, network protocols, etc.) can be in a state
- of development where the functionality, stability, or the level of
- testing is not yet high enough for general use. This is usually
- known as the "alpha-test" phase among developers. If a feature is
- currently in alpha-test, then the developers usually discourage
- uninformed widespread use of this feature by the general public to
- avoid "Why doesn't this work?" type mail messages. However, active
- testing and use of these systems is welcomed. Just be aware that it
- may not meet the normal level of reliability or it may fail to work
- in some special cases. Detailed bug reports from people familiar
- with the kernel internals are usually welcomed by the developers
- (before submitting bug reports, please read the documents
- , , ,
- , and
-  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 , ,
+ , ,
+ and  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 a

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

[Nick Andrew]

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

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

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

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

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

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

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

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

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

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

[Nick Andrew]

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

That is much nicer, thanks.

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

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

Now:


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

- Say N if unsure.
+ See  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  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  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.
--
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/

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

[Nick Andrew]

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

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

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

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

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

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

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

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

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

[Nick Andrew]

On Tue, Feb 19, 2008 at 09:39:58AM -0600, Paul Jackson wrote:
> I don't think /proc//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//cpuset file"
depends on CPUSETS
default y
+   help
+ This option provides the /proc//cpuset file.
+
+ This file contains the name of the cpuset in which
+ the process is executing. For more information, see
+ 
+
+ 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.
--
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/

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

[Nick Andrew]

Rewrite the help descriptions for clarity, accuracy and consistency.

Kernel config options affected:

  - NAMESPACES
  - UTS_NS
  - IPC_NS
  - USER_NS
  - PID_NS

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


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

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

[Nick Andrew]

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

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


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

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

  See  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/

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

[Nick Andrew]

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

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

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

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>

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

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>


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

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>

--- a/init/Kconfig  2008-02-20 00:45:07.0 +1100
+++ b/init/Kconfig  2008-02-20 00:52:07.0 +1100
@@ -439,10 +439,14 @@ menuconfig EMBEDDED
bool "Configure standard kernel features (for small systems)"
help
  This option allows certain base kernel options and settings
-  to be disabled or tweaked. This is for specialized
-  environments which can tolerate a "non-standard" kernel.
+ to be disabled or tweaked. This is for embedded systems and
+ specialized environments which can tolerate a "non-standard"
+ kernel.
+
   Only use this if you really know what you are doing.
 
+ If unsure, say N.
+
 config UID16
bool "Enable 16-bit UID system calls" if EMBEDDED
depends on ARM || BLACKFIN || CRIS || FRV || H8300 || X86_32 || M68K || 
(S390 && !64BIT) || SUPERH || SPARC32 || (SPARC64 && SPARC32_COMPAT) || UML || 
(X86_64 && IA32_EMULATION)
@@ -460,51 +464,62 @@ config SYSCTL_SYSCALL
  using paths with ascii names is now the primary path to this
  information.
 
- Almost nothing using the binary sysctl interface so if you are
+ Almost nothing uses the binary sysctl interface so if you are
  trying to save some space it is probably safe to disable this,
  making your kernel marginally smaller.
 
- If unsure say Y here.
+ If unsure, say Y.
 
 config KALLSYMS
-bool "Load all symbols for debugging/ksymoops" if EMBEDDED
-default y
-help
-  Say Y here to let the kernel print out symbolic crash information and
-  symbolic stack backtraces. This increases the size of the kernel
-  somewhat, as all symbols have to be loaded into the kernel image.
+   bool "Load all symbols for debugging/ksymoops" if EMBEDDED
+   default y
+   help
+ This information causes the kernel to print out symbolic crash
+ information and symbolic stack backtraces.
+
+ It increases the size of the kernel somewhat, as all symbols
+ have to be loaded into the kernel image.
+
+ If unsure, say Y.
 
 config KALLSYMS_ALL
bool "Include all symbols in kallsyms"
depends on DEBUG_KERNEL && KALLSYMS
help
-  Normally kallsyms only contains the symbols of functions, for nicer
-  OOPS messages.  Some debuggers can use kallsyms for other
-  symbols too: say Y here to include all symbols, if you need them 
-  and you don't care about adding 300k to the size of your kernel.
+ Normally kallsyms only contains the symbols of functions, for nicer
+ OOPS messages.  Some debuggers can use kallsyms for other
+ symbols too: say Y here to include all symbols, if you need them.
+
+ Your kernel size will increase by around 300k.
 
-  Say N.
+ If unsure, say N.
 
 config KALLSYMS_EXTRA_PASS
bool "Do an extra kallsyms pass"
depends on KALLSYMS
help
-  If kallsyms is not working correctly, the build will fail with
-  inconsistent kallsyms data.  If that occurs, log a bug report and
-  turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
-  Always say N here unless you find a bug in kallsyms, which must be
-  reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
-  you wait for kallsyms to be fixed.
+ If kallsyms is not working correctly, the build will fail with
+ inconsistent kallsyms data.  If that occurs, log a bug report and
+ turn on KALLSYMS_EXTRA_PASS which should result in a stable build.
+
+ Always say N here unless you find a bug in kallsyms, which must be
+ reported.  KALLSYMS_EXTRA_PASS is only a temporary workaround while
+ you wait for kallsyms to be fixed.
 
+ If unsure, say N.
 
 config HOTPLUG
bool "Support for hot-pluggable devices" if EMBEDDED
default y
help
  This option is provided for the case where no hotplug or uevent
- capabilities is wanted by the kernel.  You s

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>


--- a/init/Kconfig  2008-02-20 00:45:07.0 +1100
+++ b/init/Kconfig  2008-02-20 00:52:07.0 +1100
@@ -289,10 +289,16 @@ config LOG_BUF_SHIFT
 config CGROUPS
bool "Control Group support"
help
- This option will let you use process cgroup subsystems
- such as Cpusets
+ Control Groups enables processes to be tracked and grouped
+ into "cgroups". This enables you, for example, to associate
+ cgroups with certain CPU sets using "cpusets".
 
- Say N if unsure.
+ When enabled, a new filesystem type "cgroup" is available
+ and can be mounted to control cpusets.
+
+ See  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  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  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  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 :-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//cpuset file"
depends on CPUSETS
default y
+   help
+ This option provides the legacy /proc//cpuset file.
+
+ It has been deprecated in favour of an additional line
+ in /proc//status showing on which CPUs a process
+ may be scheduled.
+
+ If unsure, say Y.
 
 config RELAY
bool "Kernel->user space relay support (formerly relayfs)"
--
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/

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

[Nick Andrew]

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

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

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

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

To make a guess at it, how about:

   Enable support for user namespaces.

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

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

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

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>


--- a/init/Kconfig  2008-02-20 00:45:07.0 +1100
+++ b/init/Kconfig  2008-02-20 00:52:07.0 +1100
@@ -254,20 +254,30 @@ config IKCONFIG
tristate "Kernel .config support"
---help---
  This option enables the complete Linux kernel ".config" file
- contents to be saved in the kernel. It provides documentation
- of which kernel options are used in a running kernel or in an
- on-disk kernel.  This information can be extracted from the kernel
- image file with the script scripts/extract-ikconfig and used as
- input to rebuild the current kernel or to build another kernel.
- It can also be extracted from a running kernel by reading
- /proc/config.gz if enabled (below).
+ contents to be saved in the kernel.
+
+ It provides documentation of which kernel options are used in
+ a running kernel or in an on-disk kernel.  This information
+ can be extracted from the kernel image file with the script
+ "scripts/extract-ikconfig" and used as input to rebuild the
+ current kernel or to build another kernel.
+
+ It can also be extracted from a running kernel with
+ "zcat /proc/config.gz" if CONFIG_IKCONFIG_PROC is enabled
+ below.
+
+ Your kernel size will increase by around 14k.
+
+ If unsure, say N.
 
 config IKCONFIG_PROC
bool "Enable access to .config through /proc/config.gz"
depends on IKCONFIG && PROC_FS
---help---
- This option enables access to the kernel configuration file
- through /proc/config.gz.
+ This option enables access to the configuration of the running
+ kernel through /proc/config.gz.
+
+ If unsure, say Y.
 
 config LOG_BUF_SHIFT
int "Kernel log buffer size (16 => 64KB, 17 => 128KB)"
@@ -277,14 +287,15 @@ config LOG_BUF_SHIFT
default 15 if SMP
default 14
help
- Select kernel log buffer size as a power of 2.
- Defaults and Examples:
+ Select the kernel log buffer size as a power of 2.
+
+ Defaults and examples:
 17 => 128 KB for S/390
-16 => 64 KB for x86 NUMAQ or IA-64
-15 => 32 KB for SMP
-14 => 16 KB for uniprocessor
-13 =>  8 KB
-12 =>  4 KB
+16 =>  64 KB for x86 NUMAQ or IA-64
+15 =>  32 KB for SMP
+14 =>  16 KB for uniprocessor
+13 =>   8 KB
+12 =>   4 KB
 
 config CGROUPS
bool "Control Group support"
@@ -389,11 +400,14 @@ config PROC_PID_CPUSET
 config RELAY
bool "Kernel->user space relay support (formerly relayfs)"
help
- This option enables support for relay interface support in
+ This option enables support for the relay interface in
  certain file systems (such as debugfs).
+
  It is designed to provide an efficient mechanism for tools and
  facilities to relay large amounts of data from kernel space to
- user space.
+ userspace.
+
+ See  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  for details.
+ etc.
+ 
+ For more information, see:
+ 
+ 
 
  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
 
--
To unsubscr

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>

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

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>

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

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
 
--- a/init/Kconfig  2008-02-20 00:45:07.0 +1100
+++ b/init/Kconfig  2008-02-20 00:52:07.0 +1100
@@ -12,33 +12,45 @@ menu "General setup"
 config EXPERIMENTAL
bool "Prompt for development and/or incomplete code/drivers"
---help---
- Some of the various things that Linux supports (such as network
- drivers, file systems, network protocols, etc.) can be in a state
- of development where the functionality, stability, or the level of
- testing is not yet high enough for general use. This is usually
- known as the "alpha-test" phase among developers. If a feature is
- currently in alpha-test, then the developers usually discourage
- uninformed widespread use of this feature by the general public to
- avoid "Why doesn't this work?" type mail messages. However, active
- testing and use of these systems is welcomed. Just be aware that it
- may not meet the normal level of reliability or it may fail to work
- in some special cases. Detailed bug reports from people familiar
- with the kernel internals are usually welcomed by the developers
- (before submitting bug reports, please read the documents
- , , ,
- , and
-  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 , ,
+ , ,
+ and  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 wi

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

[Nick Andrew]

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

Rationale:

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


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

  - Uses arcane terminology which only kernel developers can understand

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

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

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

  - Poor grammar or layout.


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

  1 - Single sentence summary of what the option does

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

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

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

Patch 1
EXPERIMENTAL
LOCALVERSION
LOCALVERSION_AUTO
SWAP
SYSVIPC
POSIX_MQUEUE
BSD_PROCESS_ACCT
BSD_PROCESS_ACCT_V3

Patch 2
TASKSTATS
TASK_DELAY_ACCT
TASK_XACCT
TASK_IO_ACCOUNTING

Patch 3
USER_NS
PID_NS

Patch 4
AUDIT
AUDITSYSCALL

Patch 5
IKCONFIG
IKCONFIG_PROC
LOG_BUF_SHIFT
SYSFS_DEPRECATED
RELAY
BLK_DEV_INITRD

Patch 6
CGROUPS
CGROUP_DEBUG
CPUSETS
FAIR_GROUP_SCHED
FAIR_CGROUP_SCHED
CGROUP_CPUACCT
PROC_PID_CPUSET

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

Patch 8
SLUB_DEBUG
SLAB
SLUB
SLOB

Patch 9
MODULES
MODULE_UNLOAD
MODULE_FORCE_UNLOAD
MODVERSIONS
MODULE_SRCVERSION_ALL
KMOD

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>
-- 
PGP Key ID = 0x418487E7  http://www.nick-andrew.net/
PGP Key fingerprint = B3ED 6894 8E49 1770 C24A  67E3 6266 6EB9 4184 87E7
--
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/

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

[Nick Andrew]

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

Changelog:

Improve usefulness and consistency of kernel configuration help messages.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>

--- a/init/Kconfig  2008-02-20 00:45:07.0 +1100
+++ b/init/Kconfig  2008-02-20 00:52:07.0 +1100
@@ -169,42 +169,52 @@ config TASKSTATS
depends on NET
default n
help
- Export selected statistics for tasks/processes through the
- generic netlink interface. Unlike BSD process accounting, the
- statistics are available during the lifetime of tasks/processes as
- responses to commands. Like BSD accounting, they are sent to user
- space on task exit.
+ Taskstats is a netlink-based interface for sending per-task
+ and per-process statistics from the kernel to userspace.
 
- Say N if unsure.
+ Unlike BSD process accounting, the statistics are available
+ during the lifetime of tasks/processes as responses to
+ commands. Like BSD accounting, they are sent to user space on
+ task exit.
+
+ Netlink is a type of network socket used to transfer data
+ between the kernel and user space. For more information on
+ Netlink see <http://qos.ittc.ku.edu/netlink/html/index.html>
+
+ See  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)"
--
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/

Trivial patch to Documentation/i386/IO-APIC.txt

[Nick Andrew]

The description of the interrupt routing doesn't match the (nice) diagram.

Signed-off-by: Nick Andrew <[EMAIL PROTECTED]>

Nick.

--- a/Documentation/i386/IO-APIC.txt2007-10-10 06:31:38.0 +1000
+++ b/Documentation/i386/IO-APIC.txt2008-02-12 11:57:08.0 +1100
@@ -68,7 +68,7 @@
 
 These INTA-D PCI IRQs are always 'local to the card', their real meaning
 depends on which slot they are in. If you look at the daisy chaining diagram,
-a card in slot4, issuing INTA IRQ, it will end up as a signal on PIRQ2 of
+a card in slot4, issuing INTA IRQ, it will end up as a signal on PIRQ4 of
 the PCI chipset. Most cards issue INTA, this creates optimal distribution
 between the PIRQ lines. (distributing IRQ sources properly is not a
 necessity, PCI IRQs can be shared at will, but it's a good for performance
--
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/