stripping down the kernel-parameters.txt file

stripping down the kernel-parameters.txt file

[Robert P. J. Day]

  while killing some time between compiles and ridding the
kernel-parameters.txt file of out-of-date or incorrect cruft, it
occurs to me that that file is borderline valueless since it
apparently tries to document every possible boot-time parameter,
including those associated with individual modules.  that's just
silly.

  it would make far more sense if that file restricted itself to just
those parameters that you'd consider fundamental or basic -- those
defined with one of "__setup()" or "early_param()" that would apply to
most users.

  instead, you find stuff like this (a random example):

  bttv.card=      [HW,V4L] bttv (bt848 + bt878 based grabber cards)
  bttv.radio=     Most important insmod options are available as
                  kernel args too.
  bttv.pll=       See Documentation/video4linux/bttv/Insmod-options
  bttv.tuner=     and Documentation/video4linux/bttv/CARDLIST

not to belittle the bttv module but, really, is that information
worthy of being recorded in the top-level parms.txt file?  and if
you're going to be consistent, you'd want to do that for every single
module and its respective throughout the tree, at which the parms.txt
file collapses under its own weight from forever being updated and has
so much information that it's impossible to find the useful stuff.

  i suggest that that file record only the basic boot-time params, and
the documentation for module-specific parameters be moved closer to
the module source itself.  there's no point in that poor file trying
to keep up with all of the module development in the tree.

rday

p.s.  and, while we're at it, folks might like to start replacing
the calls to "__setup()" in their driver code with the newer module
parameters mechanism.  it's just a thought.  :-)


-- 
========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: stripping down the kernel-parameters.txt file

[David Newall]

Robert P. J. Day wrote:
>   while killing some time between compiles and ridding the
> kernel-parameters.txt file of out-of-date or incorrect cruft, it
> occurs to me that that file is borderline valueless since it
> apparently tries to document every possible boot-time parameter,
> including those associated with individual modules.  that's just
> silly.
>   

"Silly" is such a negative word.  I think it's aspirational.  It 
probably can't be achieved, but that's no reason to give up, nor to 
remove existing text.

>   i suggest that that file record only the basic boot-time params, and
> the documentation for module-specific parameters be moved closer to
> the module source itself.  there's no point in that poor file trying
> to keep up with all of the module development in the tree.

Better yet, would be if module maintainers updated the file as they 
update their modules.

Re: stripping down the kernel-parameters.txt file

[Robert P. J. Day]

On Wed, 12 Sep 2007, David Newall wrote:

> Robert P. J. Day wrote:
> >   while killing some time between compiles and ridding the
> > kernel-parameters.txt file of out-of-date or incorrect cruft, it
> > occurs to me that that file is borderline valueless since it
> > apparently tries to document every possible boot-time parameter,
> > including those associated with individual modules.  that's just
> > silly.
>
> "Silly" is such a negative word.  I think it's aspirational.  It
> probably can't be achieved, but that's no reason to give up, nor to
> remove existing text.

if the goal is to simply put all of the basic boot-time kernel parms
along with the module-specific ones into a single file, sorted in
alphabetical order, then i contend that this is, in fact, "silly".
the end result would be a somewhat chaotic mess since i think it's
clear that those "basic" kernel parms (as i call them) are
qualitatively different from the module-specific ones, and should be
segregated as such.

now, if they're still going to go into a single file, it *would* make
sense to put the basic ones at the top and, following that, the
module-specific ones, one module at a time.  *that* would make perfect
sense.  but to mix them as they are now doesn't.

rday

p.s.  by "basic", i mean those boot-time parms defined by either
"__setup()" or "early_param()".  which means that module writers
should, as much as possible, stop using those macros to define
command-line parameters for their modules.  that would go a long way
to restoring some order, and allowing for some decent and readable
documentation.

--
========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: stripping down the kernel-parameters.txt file

[David Newall]

Robert P. J. Day wrote:
> if the goal is to simply put all of the basic boot-time kernel parms
> along with the module-specific ones into a single file, sorted in
> alphabetical order, then i contend that this is, in fact, "silly".
>   

Or even, "messy".  There's no doubt that it should be maintained with 
care; perhaps it would if the people who write the code for each 
parameter also update the documentation.

Re: stripping down the kernel-parameters.txt file

[Robert P. J. Day]

On Wed, 12 Sep 2007, David Newall wrote:

> Robert P. J. Day wrote:
> > if the goal is to simply put all of the basic boot-time kernel parms
> > along with the module-specific ones into a single file, sorted in
> > alphabetical order, then i contend that this is, in fact, "silly".
>
> Or even, "messy".  There's no doubt that it should be maintained
> with care; perhaps it would if the people who write the code for
> each parameter also update the documentation.

  or (and here's a wild and crazy idea) what about writing a utility
that auto-generates all that information?

  the biggest hassle in keeping all the documentation up to date is
that much of it is being stored in a manually-updated text file
(MAINTAINERS leaps to mind), so *of course* it's always going to be
out of date.  so why not just fix it so it's auto-generated, the same
way the in-kernel nano-doc stuff is?

  surely, it wouldn't be that hard, at least for the basic parms.  a
combination of egrep, sed and sort would certainly give you the basic
parms.  off the top of my head:

$ egrep '(__setup|early_param)' $(find . -name *.c) | \
> sed -e 's/.*"\(.*\)".*/\1/' | \
> sort -u
$

  of course that's not sufficient, but it took me all of two minutes.
would it be that much work to extend it and deal with once and for
all?

rday
-- 
========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: stripping down the kernel-parameters.txt file

[Rogan Dawes]

Robert P. J. Day wrote:
> p.s.  by "basic", i mean those boot-time parms defined by either
> "__setup()" or "early_param()".  which means that module writers
> should, as much as possible, stop using those macros to define
> command-line parameters for their modules.  that would go a long way
> to restoring some order, and allowing for some decent and readable
> documentation.

Are you forgetting that modules can often be compiled into the bzImage, 
too, making them genuine boot-time params?

Rogan

Re: stripping down the kernel-parameters.txt file

[Robert P. J. Day]

On Wed, 12 Sep 2007, Rogan Dawes wrote:

> Robert P. J. Day wrote:
> > p.s.  by "basic", i mean those boot-time parms defined by either
> > "__setup()" or "early_param()".  which means that module writers
> > should, as much as possible, stop using those macros to define
> > command-line parameters for their modules.  that would go a long
> > way to restoring some order, and allowing for some decent and
> > readable documentation.
>
> Are you forgetting that modules can often be compiled into the
> bzImage, too, making them genuine boot-time params?

<sarcasm>
really?  no way.  get outta town.
</sarcasm>

  sorry, but there was no way i could resist that.  :-)  *of course* i
realize that.  *all* of those things (__setup, early_param, actual
module params) are potential entries on the kernel line at boot time,
depending on your particular configuration.

  all i'm suggesting is that there is an obvious distinction between
those that are defined using __setup() or early_param(), and those
that are actual module parameters.  and that it would make more sense
to keep them separate, even if only separating them within the same
text file.

  in the end, there should be a nice, *short* reference for what i
like to call "basic" kernel parms (defined by __setup() or
early_param()), while anyone who wants to learn about any
module-specific parms should then have to go look up the info for that
given module, that's all.

  as a trivial starting point, this would involve nothing more than
shifting current content around in kernel-parameters.txt, putting the
basic stuff at the top, and the module-specific stuff after that.
heck, that would even give module authors the chance to add a line or
two of module description if they wanted.  how does life get any
better than that?

rday
-- 
========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
========================================================================

Re: stripping down the kernel-parameters.txt file

[Kyle Moffett]

On Sep 12, 2007, at 10:44:29, Robert P. J. Day wrote:
> in the end, there should be a nice, *short* reference for what i  
> like to call "basic" kernel parms (defined by __setup() or  
> early_param()), while anyone who wants to learn about any module- 
> specific parms should then have to go look up the info for that  
> given module, that's all.
>
> as a trivial starting point, this would involve nothing more than  
> shifting current content around in kernel-parameters.txt, putting  
> the basic stuff at the top, and the module-specific stuff after  
> that.  heck, that would even give module authors the chance to add  
> a line or two of module description if they wanted.  how does life  
> get any better than that?

Well, maybe if modules could be used similarly to: "modprobe  
my_module --help" to give a description of the available module  
parameters.  That information might be merged into modules from text  
file(s) or vice-versa, but I can see it being significantly more  
useful.  Another mildly-useful feature would be to stick the basic  
boot params and those for built-in modules into a little text file  
which could optionally be embedded in the initramfs along with the  
"less" binary, so that a "vmlinuz --help" could be made to work  
usefully from your bootloader.

Cheers,
Kyle Moffett

Re: stripping down the kernel-parameters.txt file

[Randy Dunlap]

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

On Wed, 12 Sep 2007 13:47:38 -0400 Kyle Moffett wrote:

> On Sep 12, 2007, at 10:44:29, Robert P. J. Day wrote:
> > in the end, there should be a nice, *short* reference for what i  
> > like to call "basic" kernel parms (defined by __setup() or  
> > early_param()), while anyone who wants to learn about any module- 
> > specific parms should then have to go look up the info for that  
> > given module, that's all.
> >
> > as a trivial starting point, this would involve nothing more than  
> > shifting current content around in kernel-parameters.txt, putting  
> > the basic stuff at the top, and the module-specific stuff after  
> > that.  heck, that would even give module authors the chance to add  
> > a line or two of module description if they wanted.  how does life  
> > get any better than that?
> 
> Well, maybe if modules could be used similarly to: "modprobe  
> my_module --help" to give a description of the available module  
> parameters.  That information might be merged into modules from text  

modinfo prints out all MODULE_PARM_DESC() strings.

> file(s) or vice-versa, but I can see it being significantly more  
> useful.  Another mildly-useful feature would be to stick the basic  
> boot params and those for built-in modules into a little text file  
> which could optionally be embedded in the initramfs along with the  
> "less" binary, so that a "vmlinuz --help" could be made to work  
> usefully from your bootloader.

This has come up before.  I wrote the attached 'module-params'
script last October (2006).  It can search .c files or .ko files
for module parameters...

---
~Randy

[-- Attachment #2: module-params --]
[-- Type: application/octet-stream, Size: 2041 bytes --]

#! /bin/sh
# Copyright (C) 2006 Randy Dunlap
# GPL version 2 license.
# prints 'modinfo -p' for all found *.ko files
# prints 'modinfo' (all) for all found *.ko files if -a is specified;
# prints all MODULE_PARM_DESC lines for all *.c files if -s is specified;

allinfo=""
sources=""

while getopts "aosh" Option ; do
	case $Option in
	a)
		allinfo="1"
		;;
	s)
		sources="1"
		;;
	o)
		sources=""
		;;
	h|*)
		echo "usage: module-params [-a] [-s] [-o] [-h]"
		echo "lists module parameter info for all found files:"
		echo "  -s searches source (.c) files"
		echo "  -o searches binary (.ko) files [default]"
		echo "  -a lists all modinfo output from .ko files"
		echo "     (else just -p: module parameters output)"
		echo "  -h prints this help text"
		exit
		;;
	esac
done
##echo shifting args by: $(($OPTIND - 1))
shift $(($OPTIND - 1))

if [ "$allinfo" == "1" ]; then
	modinfo_param=""
else
	modinfo_param="-p"	# module parameters only
fi

if [ "$sources" == "1" ]; then
	filenames=$(find . -name \*\.c)
else
	filenames=$(find . -name \*\.ko)
fi

for file in $filenames ; do

	if [ "$sources" == "1" ]; then
		grep -sq -w MODULE_PARM_DESC $file
		sts=$?

		if [ $sts -eq 0 ]; then
			if [ ${file:0:2} == "./" ]; then
				file=${file:2}
			fi
			echo "$file:"
			grep -w MODULE_PARM_DESC $file | \
				sed -e s/MODULE_PARM_DESC[[:space:]]*\(// | \
				sed -e s/"\"[[:space:]]*)[[:space:]]*;[[:space:]]*$"// |
				sed -e s/","/": "/ |
				sed -e s/'"$'/''/ |
				sed -e s/'\\$'/''/ |
				sed -e s/'\\n$'/''/ |
				sed -e s/'\\t'/' '/g |
				sed -e s/'\\n'/': '/g |
				sed -e s/'\\'/''/g |
				sed -e s/'__MODULE_STRING'/''/g |
				sed -e s/":[[:space:]]*\""/": "/
			echo "-------------------------------------------------"
		fi

	else	# object modules
		info=`modinfo $modinfo_param $file`
		if [ "$info" != "" ]; then
			# don't repeat filename
			if [ "$allinfo" != "1" ]; then
				echo "$file:"
			fi
			modinfo $modinfo_param $file | sed -e s/":"/": "/g
			echo "-------------------------------------------------"
		fi

	fi

done