2005-02-01 00:01:51

by Matt Domsch

[permalink] [raw]
Subject: [RFC][PATCH 2.6.11-rc2] vmlinux: add SETUP_DESC() to describe __setup() options

__setup() options are traditionally documented in
Documentation/kernel-parameters.txt. However, it would be nice if
they could be documented alongside the implementation, similar to
MODULE_PARM_DESC() fields for modules, and if 'modinfo vmlinux' could
report such.

Patch below adds a new macro, SETUP_DESC(), which can be used to
document the use cases of __setup() options. A usage example in
kernel/audit.c is provided as well.

$ modinfo vmlinux | grep setup_param
setup_param: audit:0 = disable, 1 = enable (kernel/audit.c)

Feedback requested.

Thanks,
Matt

--
Matt Domsch
Software Architect
Dell Linux Solutions linux.dell.com & http://www.dell.com/linux
Linux on Dell mailing lists @ http://lists.us.dell.com

===== include/linux/init.h 1.35 vs edited =====
--- 1.35/include/linux/init.h 2005-01-04 20:48:02 -06:00
+++ edited/include/linux/init.h 2005-01-31 17:22:41 -06:00
@@ -127,6 +127,15 @@
__attribute__((aligned((sizeof(long))))) \
= { __setup_str_##unique_id, fn, early }

+#define __setup_cat(a) __setup_str_ ## a
+#define __SETUP_INFO(tag, name, info) \
+static const char __setup_cat(name)[] \
+ __attribute_used__ \
+ __attribute__((section(".modinfo"),unused)) = __stringify(tag) "=" info " (" __FILE__ ")"
+
+#define SETUP_DESC(_parm, desc) \
+ __SETUP_INFO(setup_param, _parm, #_parm ":" desc)
+
#define __setup_null_param(str, unique_id) \
__setup_param(str, unique_id, NULL, 0)

@@ -202,6 +211,7 @@
#define __setup_null_param(str, unique_id) /* nothing */
#define __setup(str, func) /* nothing */
#define __obsolete_setup(str) /* nothing */
+#define SETUP_DESC(_parm, desc) /* nothing */
#endif

/* Data marked not to be saved by software_suspend() */



===== kernel/audit.c 1.6 vs edited =====
--- 1.6/kernel/audit.c 2005-01-20 22:56:04 -06:00
+++ edited/kernel/audit.c 2005-01-31 15:55:43 -06:00
@@ -617,7 +617,7 @@
}

__setup("audit=", audit_enable);
-
+SETUP_DESC(audit, "0 = disable, 1 = enable");

/* Obtain an audit buffer. This routine does locking to obtain the
* audit buffer, but then no locking is required for calls to


2005-02-01 01:10:19

by Rusty Russell

[permalink] [raw]
Subject: Re: [RFC][PATCH 2.6.11-rc2] vmlinux: add SETUP_DESC() to describe __setup() options

On Mon, 2005-01-31 at 17:50 -0600, Matt Domsch wrote:
> __setup() options are traditionally documented in
> Documentation/kernel-parameters.txt. However, it would be nice if
> they could be documented alongside the implementation, similar to
> MODULE_PARM_DESC() fields for modules, and if 'modinfo vmlinux' could
> report such.
>
> Patch below adds a new macro, SETUP_DESC(), which can be used to
> document the use cases of __setup() options. A usage example in
> kernel/audit.c is provided as well.

I don't want to encourage the proliferation of __setup, and prefer
module_parm() for new code. __setup() is good for certain fundamentals,
but the namespace and parsing help given by module_parm() usually makes
it a better choice.

That said, I don't have a particular issue with this.
Rusty.
--
A bad analogy is like a leaky screwdriver -- Richard Braakman