[patch 0/5] autoparam v0.2: generating parameter descriptions on compile

[patch 0/5] autoparam v0.2: generating parameter descriptions on compile

[domen]

Hi!

The purpose of autoparam is to generate boot parameter descriptions
from sources. It does that by creating a new section called
__param_strings. (The interesting bits here are from Magnus Damm.)
It fills a gap about undocumented boot options from modules.

It consists of 5 patches:

autoparam_1-includes
  Descriptions get saved in __param_strings. Also added a new
  __setup_desc().

autoparam_2-makefile
  On every vmlinux change .kernel-parameters.o gets regenerated, and
  __param_strings removed from vmlinux. (It's still bigger than
  non-patched vmlinux, but all sections are of same length, alignment
  issues?)
  Also, a new target "make kernelparams" which generates
  Documentation/kernel-parameters-gen.txt. It should probably not be
  in $(srctree) though.
  There should be some more work done here, but I'm out of ideas ATM.

autoparam_3-extract_script
  Simple perl script to extract descriptions.

autoparam_4-af_unix_workaround
autoparam_5-ide_workaround
  Workarounds needed.


Comments, improvements?


	Domen

[patch 1/5] autoparam: includes

[domen]

[-- Attachment #1: autoparam_1-includes --]
[-- Type: text/plain, Size: 5658 bytes --]

From: Magnus Damm <damm@opensource.se>


The code of autoparam - modified include files. Stores parameter name, type
and description in a section called __param_strings.

Signed-off-by: Magnus Damm <damm@opensource.se>
Signed-off-by: Domen Puncer <domen@coderock.org>

 include/linux/init.h        |   24 ++++++++++++++++++------
 include/linux/module.h      |    8 ++++++++
 include/linux/moduleparam.h |   15 ++++++++++++---
 3 files changed, 38 insertions(+), 9 deletions(-)

Index: a/include/linux/init.h
===================================================================
--- a.orig/include/linux/init.h
+++ a/include/linux/init.h
@@ -119,19 +119,30 @@ struct obs_kernel_param {
  * Force the alignment so the compiler doesn't space elements of the
  * obs_kernel_param "array" too far apart in .init.setup.
  */
-#define __setup_param(str, unique_id, fn, early)			\
+#define __setup_param(str, unique_id, fn, early, mark)		\
 	static char __setup_str_##unique_id[] __initdata = str;	\
 	static struct obs_kernel_param __setup_##unique_id	\
 		__attribute_used__				\
 		__attribute__((__section__(".init.setup")))	\
 		__attribute__((aligned((sizeof(long)))))	\
-		= { __setup_str_##unique_id, fn, early }
+		= { __setup_str_##unique_id, fn, early };	\
+		static const char __setup_doc_##unique_id[]	\
+		__attribute_used__				\
+		__attribute__((section("__param_strings")))	\
+		= mark str
 
 #define __setup_null_param(str, unique_id)			\
-	__setup_param(str, unique_id, NULL, 0)
+	__setup_param(str, unique_id, NULL, 0, "o:")
 
 #define __setup(str, fn)					\
-	__setup_param(str, fn, fn, 0)
+	__setup_param(str, fn, fn, 0, "s:")
+
+#define __setup_desc(str, fn, desc)				\
+	__setup(str, fn);					\
+	static const char __param_doc_desc_##_parm[]		\
+	__attribute_used__					\
+	__attribute__((section("__param_strings")))		\
+	= "d:" str ":" desc
 
 #define __obsolete_setup(str)					\
 	__setup_null_param(str, __LINE__)
@@ -139,7 +150,7 @@ struct obs_kernel_param {
 /* NOTE: fn is as per module_param, not __setup!  Emits warning if fn
  * returns non-zero. */
 #define early_param(str, fn)					\
-	__setup_param(str, fn, fn, 1)
+	__setup_param(str, fn, fn, 1, "e:")
 
 /* Relies on saved_command_line being set */
 void __init parse_early_param(void);
@@ -198,9 +209,10 @@ void __init parse_early_param(void);
 	{ return exitfn; }					\
 	void cleanup_module(void) __attribute__((alias(#exitfn)));
 
-#define __setup_param(str, unique_id, fn)	/* nothing */
+#define __setup_param(str, unique_id, fn, early, mark)	/* nothing */
 #define __setup_null_param(str, unique_id) 	/* nothing */
 #define __setup(str, func) 			/* nothing */
+#define __setup_desc(str, fn, desc)		/* nothing */
 #define __obsolete_setup(str) 			/* nothing */
 #endif
 
Index: a/include/linux/module.h
===================================================================
--- a.orig/include/linux/module.h
+++ a/include/linux/module.h
@@ -131,10 +131,18 @@ extern struct module __this_module;
 /* What your module does. */
 #define MODULE_DESCRIPTION(_description) MODULE_INFO(description, _description)
 
+#ifdef MODULE
 /* One for each parameter, describing how to use it.  Some files do
    multiple of these per line, so can't just use MODULE_INFO. */
 #define MODULE_PARM_DESC(_parm, desc) \
 	__MODULE_INFO(parm, _parm, #_parm ":" desc)
+#else
+#define MODULE_PARM_DESC(_parm, desc)				\
+	static const char __param_doc_desc_##_parm[]		\
+	__attribute_used__					\
+	__attribute__((section("__param_strings")))		\
+	= "d:" __stringify(KBUILD_MODNAME) "." #_parm ":" desc
+#endif
 
 #define MODULE_DEVICE_TABLE(type,name)		\
   MODULE_GENERIC_TABLE(type##_device,name)
Index: a/include/linux/moduleparam.h
===================================================================
--- a.orig/include/linux/moduleparam.h
+++ a/include/linux/moduleparam.h
@@ -69,6 +69,12 @@ struct kparam_array
     __attribute__ ((unused,__section__ ("__param"),aligned(sizeof(void *)))) \
 	= { __param_str_##name, perm, set, get, arg }
 
+#define module_param_doc(prefix, name, type)				\
+	static const char __param_doc_##name[]				\
+	__attribute_used__						\
+	__attribute__((section("__param_strings")))			\
+	= "m:" prefix #name ":" #type
+
 #define module_param_call(name, set, get, arg, perm)			      \
 	__module_param_call(MODULE_PARAM_PREFIX, name, set, get, arg, perm)
 
@@ -78,7 +84,8 @@ struct kparam_array
 #define module_param_named(name, value, type, perm)			   \
 	param_check_##type(name, &(value));				   \
 	module_param_call(name, param_set_##type, param_get_##type, &value, perm); \
-	__MODULE_PARM_TYPE(name, #type)
+	__MODULE_PARM_TYPE(name, #type);				   \
+	module_param_doc(MODULE_PARAM_PREFIX, name, type)
 
 #define module_param(name, type, perm)				\
 	module_param_named(name, name, type, perm)
@@ -89,7 +96,8 @@ struct kparam_array
 		= { len, string };					\
 	module_param_call(name, param_set_copystring, param_get_string,	\
 		   &__param_string_##name, perm);			\
-	__MODULE_PARM_TYPE(name, "string")
+	__MODULE_PARM_TYPE(name, "string");				\
+	module_param_doc(MODULE_PARAM_PREFIX, name, type)
 
 /* Called on module insert or kernel boot */
 extern int parse_args(const char *name,
@@ -151,7 +159,8 @@ extern int param_get_invbool(char *buffe
 	    sizeof(array[0]), array };					\
 	module_param_call(name, param_array_set, param_array_get, 	\
 			  &__param_arr_##name, perm);			\
-	__MODULE_PARM_TYPE(name, "array of " #type)
+	__MODULE_PARM_TYPE(name, "array of " #type);			\
+	module_param_doc(MODULE_PARAM_PREFIX, name, type)
 
 #define module_param_array(name, type, nump, perm)		\
 	module_param_array_named(name, name, type, nump, perm)

--

[patch 2/5] autoparam: makefile

[domen]

[-- Attachment #1: autoparam_2-makefile --]
[-- Type: text/plain, Size: 2409 bytes --]

From: Domen Puncer <domen@coderock.org>


Build .kernel-parameters.o when vmlinux is (re)built.
Add target "kernelparams" which generates descriptions of parameters
in Documentation/kernel-parameters-gen.txt

Signed-off-by: Domen Puncer <domen@coderock.org>

 Makefile |   24 +++++++++++++++++++++++-
 1 files changed, 23 insertions(+), 1 deletion(-)

Index: a/Makefile
===================================================================
--- a.orig/Makefile
+++ a/Makefile
@@ -650,6 +650,7 @@ define rule_vmlinux__
 		/bin/false;                             \
 	fi;
 	$(verify_kallsyms)
+	$(extract_kernel_parameters)
 endef
 
 
@@ -916,6 +917,15 @@ modules modules_install: FORCE
 
 endif # CONFIG_MODULES
 
+# Extract kernel parameters
+# ---------------------------------------------------------------------------
+
+define extract_kernel_parameters
+	$(Q)$(OBJCOPY) -j __param_strings $(objtree)/vmlinux -O binary \
+		$(objtree)/.kernel-parameters.o
+	$(Q)$(OBJCOPY) -R __param_strings $(objtree)/vmlinux $(objtree)/vmlinux
+endef
+
 # Generate asm-offsets.h 
 # ---------------------------------------------------------------------------
 
@@ -946,7 +956,8 @@ endef
 # Directories & files removed with 'make clean'
 CLEAN_DIRS  += $(MODVERDIR)
 CLEAN_FILES +=	vmlinux System.map \
-                .tmp_kallsyms* .tmp_version .tmp_vmlinux* .tmp_System.map
+                .tmp_kallsyms* .tmp_version .tmp_vmlinux* .tmp_System.map \
+		.kernel-parameters.o
 
 # Directories & files removed with 'make mrproper'
 MRPROPER_DIRS  += include/config include2
@@ -1048,6 +1059,8 @@ help:
 	@echo  ''
 	@echo  'Documentation targets:'
 	@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
+	@echo  '  kernelparams    - Generates list of boot parameters in'
+	@echo  '                    Documentation/kernel-parameters-gen.txt'
 	@echo  ''
 	@echo  'Architecture specific targets ($(ARCH)):'
 	@$(if $(archhelp),$(archhelp),\
@@ -1142,6 +1155,15 @@ help:
 	@echo  ''
 endif # KBUILD_EXTMOD
 
+
+kernelparams:
+	$(Q)if [ ! -f $(objtree)/.kernel-parameters.o ]; then \
+		echo "You have to build a kernel (vmlinux) first."; \
+		exit 1; \
+	fi
+	$(O)$(PERL) -w $(srctree)/scripts/kernelparams.pl $(objtree)/.kernel-parameters.o \
+		> $(srctree)/Documentation/kernel-parameters-gen.txt
+
 # Generate tags for editors
 # ---------------------------------------------------------------------------
 

--

[patch 3/5] autoparam: extract script

[domen]

[-- Attachment #1: autoparam_3-extract_script --]
[-- Type: text/plain, Size: 1617 bytes --]

From: Domen Puncer <domen@coderock.org>


A simple perl script which extracts parameters, types and
descriptions from binary file.

Signed-off-by: Domen Puncer <domen@coderock.org>

 scripts/kernelparams.pl |   49 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 49 insertions(+)

Index: a/scripts/kernelparams.pl
===================================================================
--- /dev/null
+++ a/scripts/kernelparams.pl
@@ -0,0 +1,49 @@
+#!/usr/bin/perl
+use strict;
+my ($p, @params, %param_t, %param_d);
+
+while (<>) {
+	my @params = split '\0', $_;
+	foreach $p (@params) {
+		next if (!$p);
+		# module_param, "m:module.param:type"
+		if ($p =~ /^(m:.+?):(.*)/) {
+			$param_t{$1} = " ($2)";
+		}
+		# __setup, "s:"; obsolete_setup; early_param
+		elsif ($p =~ /^([soe]:.+)/) {
+			$param_t{$1} = '';
+		}
+		# description, "d:module.param:description"
+		elsif ($p =~ /^d:(.+?):(.+)/) {
+			$param_d{$1} = $2;
+		}
+		# i.e. ide uses __setup("", blah)
+		elsif ($p !~ /^[soe]:$/) {
+			print STDERR "Parameter error: \"$p\"\n";
+		}
+	}
+}
+
+# print the parameters
+foreach $p (sort(keys(%param_t))) {
+	print "$p$param_t{$p}\n";
+	my $pn = substr($p, 2);
+	if (!$param_d{$pn}) {
+		# only warn for module parameters
+		if ($p =~ "^m:") {
+			print "  No description\n";
+		}
+	} else {
+		print "  $param_d{$pn}\n";
+	}
+	print "\n";
+}
+
+# descriptions alone; typos, deprecated
+foreach $p (sort(keys(%param_d))) {
+	if (!exists $param_t{"m:".$p} && !exists $param_t{"s:".$p} &&
+			!exists $param_t{"o:".$p}) {
+		print STDERR "$p only has description (MODULE_PARM?)\n";
+	}
+}

--

[patch 4/5] autoparam: af_unix workaround

[domen]

[-- Attachment #1: autoparam_4-af_unix_workaround --]
[-- Type: text/plain, Size: 608 bytes --]

From: Magnus Damm <damm@opensource.se>


This is a quick fix that removes the "KBUILD_MODNAME -> unix -> 1" conflict.

Signed-off-by: Magnus Damm <damm@opensource.se>
Signed-off-by: Domen Puncer <domen@coderock.org>

 net/unix/af_unix.c |    2 ++
 1 files changed, 2 insertions(+)

Index: a/net/unix/af_unix.c
===================================================================
--- a.orig/net/unix/af_unix.c
+++ a/net/unix/af_unix.c
@@ -2068,6 +2068,8 @@ static void __exit af_unix_exit(void)
 	proto_unregister(&unix_proto);
 }
 
+#undef unix
+
 module_init(af_unix_init);
 module_exit(af_unix_exit);
 

--

Re: [patch 4/5] autoparam: af_unix workaround

[Alexey Dobriyan]

On Thursday 07 July 2005 15:25, domen@coderock.org wrote:
> This is a quick fix that removes the "KBUILD_MODNAME -> unix -> 1" conflict.

> --- a.orig/net/unix/af_unix.c
> +++ a/net/unix/af_unix.c

> +#undef unix

This deserves a comment. Ditto for ide workarounds.

>  module_init(af_unix_init);
>  module_exit(af_unix_exit);

[patch 5/5] autoparam: ide workarounds

[domen]

[-- Attachment #1: autoparam_5-ide_workaround --]
[-- Type: text/plain, Size: 1949 bytes --]

From: Magnus Damm <damm@opensource.se>


This patch contains quick fixes that prevents KBUILD_MODNAME conflicts.

Signed-off-by: Magnus Damm <damm@opensource.se>
Signed-off-by: Domen Puncer <domen@coderock.org>

 drivers/ide/ide-disk.c   |    2 ++
 drivers/ide/ide-floppy.c |    2 ++
 drivers/ide/ide-tape.c   |    2 ++
 drivers/scsi/ide-scsi.c  |    2 ++
 4 files changed, 8 insertions(+)

Index: a/drivers/ide/ide-disk.c
===================================================================
--- a.orig/drivers/ide/ide-disk.c
+++ a/drivers/ide/ide-disk.c
@@ -1273,6 +1273,8 @@ static int idedisk_init (void)
 	return driver_register(&idedisk_driver.gen_driver);
 }
 
+#undef ide_disk
+
 module_init(idedisk_init);
 module_exit(idedisk_exit);
 MODULE_LICENSE("GPL");
Index: a/drivers/ide/ide-floppy.c
===================================================================
--- a.orig/drivers/ide/ide-floppy.c
+++ a/drivers/ide/ide-floppy.c
@@ -2204,6 +2204,8 @@ static int idefloppy_init (void)
 	return driver_register(&idefloppy_driver.gen_driver);
 }
 
+#undef ide_floppy
+
 module_init(idefloppy_init);
 module_exit(idefloppy_exit);
 MODULE_LICENSE("GPL");
Index: a/drivers/ide/ide-tape.c
===================================================================
--- a.orig/drivers/ide/ide-tape.c
+++ a/drivers/ide/ide-tape.c
@@ -4919,6 +4919,8 @@ static int idetape_init (void)
 	return driver_register(&idetape_driver.gen_driver);
 }
 
+#undef ide_tape
+
 module_init(idetape_init);
 module_exit(idetape_exit);
 MODULE_ALIAS_CHARDEV_MAJOR(IDETAPE_MAJOR);
Index: a/drivers/scsi/ide-scsi.c
===================================================================
--- a.orig/drivers/scsi/ide-scsi.c
+++ a/drivers/scsi/ide-scsi.c
@@ -1186,6 +1186,8 @@ static void __exit exit_idescsi_module(v
 	driver_unregister(&idescsi_driver.gen_driver);
 }
 
+#undef ide_scsi
+
 module_init(init_idescsi_module);
 module_exit(exit_idescsi_module);
 MODULE_LICENSE("GPL");

--

[PATCH 0/5] autoparam

[Magnus Damm]

Here are a set of patches that makes it possible to autogenerate kernel command
line documentation from the source code. The approach is rather straightforward
- the parameter name, the type and the description are stored in a section 
called __param_strings. After vmlinux is built this section is extracted using
objcopy and a script is used to generate a primitive - but up to date - 
document.

Right now the section is left in the kernel binary. The document is currently
not generated from the Makefile, so the curious user should perform:

$ objcopy -j __param_strings vmlinux -O binary foo
$ chmod a+x scripts/section2text.rb
$ cat foo | ./scripts/section2text.rb

And yeah, you need to install ruby to run the script.

The ruby script section2text.rb does some checks to see if MODULE_PARM_DESC()
is used without module_param(). You will find interesting typos.

Future work that extends this idea could include replacing __setup(name) with 
__setup(name, descr). And storing the documentation somewhere to make it easy
for the end user to look up the generated parameter list from the boot loader.

/ magnus

[PATCH 1/5] autoparam: includes

[Magnus Damm]

The code of autoparam - modified include files. Stores parameter name, type 
and description in a section called __param_strings.  

Signed-off-by: Magnus Damm <damm@opensource.se>

diff -urN linux-2.6.12-rc1/include/linux/init.h linux-2.6.12-rc1-autoparam/include/linux/init.h
--- linux-2.6.12-rc1/include/linux/init.h	2005-03-20 18:09:16.000000000 +0100
+++ linux-2.6.12-rc1-autoparam/include/linux/init.h	2005-03-20 22:24:14.393451896 +0100
@@ -125,7 +125,11 @@
 		__attribute_used__				\
 		__attribute__((__section__(".init.setup")))	\
 		__attribute__((aligned((sizeof(long)))))	\
-		= { __setup_str_##unique_id, fn, early }
+		= { __setup_str_##unique_id, fn, early };	\
+		static const char __setup_doc_##unique_id[]	\
+		__attribute_used__				\
+		__attribute__((section("__param_strings")))	\
+		= str
 
 #define __setup_null_param(str, unique_id)			\
 	__setup_param(str, unique_id, NULL, 0)
diff -urN linux-2.6.12-rc1/include/linux/module.h linux-2.6.12-rc1-autoparam/include/linux/module.h
--- linux-2.6.12-rc1/include/linux/module.h	2005-03-20 18:20:18.000000000 +0100
+++ linux-2.6.12-rc1-autoparam/include/linux/module.h	2005-03-20 22:26:33.666279208 +0100
@@ -128,10 +128,18 @@
 /* What your module does. */
 #define MODULE_DESCRIPTION(_description) MODULE_INFO(description, _description)
 
+#ifdef MODULE
 /* One for each parameter, describing how to use it.  Some files do
    multiple of these per line, so can't just use MODULE_INFO. */
 #define MODULE_PARM_DESC(_parm, desc) \
 	__MODULE_INFO(parm, _parm, #_parm ":" desc)
+#else
+#define MODULE_PARM_DESC(_parm, desc)				\
+	static const char __param_doc_desc_##_parm[]		\
+	__attribute_used__					\
+	__attribute__((section("__param_strings")))		\
+	= __stringify(KBUILD_MODNAME) "." #_parm " () " desc
+#endif
 
 #define MODULE_DEVICE_TABLE(type,name)		\
   MODULE_GENERIC_TABLE(type##_device,name)
diff -urN linux-2.6.12-rc1/include/linux/moduleparam.h linux-2.6.12-rc1-autoparam/include/linux/moduleparam.h
--- linux-2.6.12-rc1/include/linux/moduleparam.h	2005-03-20 18:20:18.000000000 +0100
+++ linux-2.6.12-rc1-autoparam/include/linux/moduleparam.h	2005-03-20 22:29:09.438598216 +0100
@@ -69,6 +69,12 @@
     __attribute__ ((unused,__section__ ("__param"),aligned(sizeof(void *)))) \
 	= { __param_str_##name, perm, set, get, arg }
 
+#define module_param_doc(prefix, name, type)				\
+	static const char __param_doc_##name[]				\
+	__attribute_used__						\
+	__attribute__((section("__param_strings")))			\
+	= prefix #name " (" #type ")"
+
 #define module_param_call(name, set, get, arg, perm)			      \
 	__module_param_call(MODULE_PARAM_PREFIX, name, set, get, arg, perm)
 
@@ -78,7 +84,8 @@
 #define module_param_named(name, value, type, perm)			   \
 	param_check_##type(name, &(value));				   \
 	module_param_call(name, param_set_##type, param_get_##type, &value, perm); \
-	__MODULE_PARM_TYPE(name, #type)
+	__MODULE_PARM_TYPE(name, #type);				   \
+	module_param_doc(MODULE_PARAM_PREFIX, name, type)
 
 #define module_param(name, type, perm)				\
 	module_param_named(name, name, type, perm)
@@ -89,7 +96,8 @@
 		= { len, string };					\
 	module_param_call(name, param_set_copystring, param_get_string,	\
 		   &__param_string_##name, perm);			\
-	__MODULE_PARM_TYPE(name, "string")
+	__MODULE_PARM_TYPE(name, "string");				\
+	module_param_doc(MODULE_PARAM_PREFIX, name, type)
 
 /* Called on module insert or kernel boot */
 extern int parse_args(const char *name,
@@ -151,7 +159,8 @@
 	    sizeof(array[0]), array };					\
 	module_param_call(name, param_array_set, param_array_get, 	\
 			  &__param_arr_##name, perm);			\
-	__MODULE_PARM_TYPE(name, "array of " #type)
+	__MODULE_PARM_TYPE(name, "array of " #type);			\
+	module_param_doc(MODULE_PARAM_PREFIX, name, type)
 
 #define module_param_array(name, type, nump, perm)		\
 	module_param_array_named(name, name, type, nump, perm)