[KJ] [PATCH] Fix for some typos in Documentation/makefiles.txt

[KJ] [PATCH] Fix for some typos in Documentation/makefiles.txt

[Bryce Harrington]

Hi Kai,

I noticed a few typos while reading makefiles.txt to learn about the
kbuild system.  Attached is a patch against 2.6.18 to fix them.

Bryce

Signed-off-by:  Bryce Harrington <bryce@osdl.org>

--- linux-2.6.18/Documentation/kbuild/makefiles.txt.orig	2006-09-19 20:42:06.000000000 -0700
+++ linux-2.6.18/Documentation/kbuild/makefiles.txt	2006-09-20 12:28:14.000000000 -0700
@@ -387,10 +387,10 @@
 
 --- 3.11 $(CC) support functions
 
-	The kernel may be build with several different versions of
+	The kernel may be built with several different versions of
 	$(CC), each supporting a unique set of features and options.
 	kbuild provide basic support to check for valid options for $(CC).
-	$(CC) is useally the gcc compiler, but other alternatives are
+	$(CC) is usually the gcc compiler, but other alternatives are
 	available.
 
     as-option
@@ -449,8 +449,8 @@
 	and $(cflags-y) will be assigned the values -a32 and -m32.
 
     cc-option-align
-	gcc version >= 3.0 shifted type of options used to speify
-	alignment of functions, loops etc. $(cc-option-align) whrn used
+	gcc version >= 3.0 shifted type of options used to specify
+	alignment of functions, loops etc. $(cc-option-align) when used
 	as prefix to the align options will select the right prefix:
 	gcc < 3.00
 		cc-option-align = -malign
@@ -529,7 +529,7 @@
 	Host programs can be made up based on composite objects.
 	The syntax used to define composite objects for host programs is
 	similar to the syntax used for kernel objects.
-	$(<executeable>-objs) list all objects used to link the final
+	$(<executable>-objs) list all objects used to link the final
 	executable.
 
 	Example:
@@ -648,7 +648,7 @@
 
 --- 4.7 Using hostprogs-$(CONFIG_FOO)
 
-	A typcal pattern in a Kbuild file lok like this:
+	A typical pattern in a Kbuild file looks like this:
 
 	Example:
 		#scripts/Makefile
@@ -680,7 +680,8 @@
 be deleted. Kbuild will assume files to be in same relative directory as the
 Makefile except if an absolute path is specified (path starting with '/').
 
-To delete a directory hirachy use:
+To delete a directory hierarchy use:
+
 	Example:
 		#scripts/package/Makefile
 		clean-dirs := $(objtree)/debian/
@@ -923,7 +924,7 @@
 		#arch/i386/Makefile
 		define archhelp
 		  echo  '* bzImage      - Image (arch/$(ARCH)/boot/bzImage)'
-		endef
+		endif
 
 	When make is executed without arguments, the first goal encountered
 	will be built. In the top level Makefile the first goal present
@@ -1011,9 +1012,9 @@
 			$(call if_changed,ld)
 
 	In this example there are two possible targets, requiring different
-	options to the linker. the linker options are specified using the
+	options to the linker.  The linker options are specified using the
 	LDFLAGS_$@ syntax - one for each potential target.
-	$(targets) are assinged all potential targets, herby kbuild knows
+	$(targets) are assigned all potential targets, thereby kbuild knows
 	the targets and will:
 		1) check for commandline changes
 		2) delete target during make clean
@@ -1067,12 +1068,12 @@
 		#Makefile
 		export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH)
 		
-	The assigment to $(always) is used to tell kbuild to build the
+	The assignment to $(always) is used to tell kbuild to build the
 	target: vmlinux.lds.
 	The assignment to $(CPPFLAGS_vmlinux.lds) tell kbuild to use the
 	specified options when building the target vmlinux.lds.
 	
-	When building the *.lds target kbuild used the variakles:
+	When building the *.lds target kbuild used the variables:
 	CPPFLAGS	: Set in top-level Makefile
 	EXTRA_CPPFLAGS	: May be set in the kbuild makefile
 	CPPFLAGS_$(@F)  : Target specific flags.
@@ -1176,3 +1177,5 @@
 - Generating offset header files.
 - Add more variables to section 7?
 
+
+
_______________________________________________
Kernel-janitors mailing list
Kernel-janitors@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/kernel-janitors

Re: [KJ] [PATCH] Fix for some typos in Documentation/makefiles.txt

[Sam Ravnborg]

On Wed, Sep 20, 2006 at 12:43:37PM -0700, Bryce Harrington wrote:
> Hi Kai,
> 
> I noticed a few typos while reading makefiles.txt to learn about the
> kbuild system.  Attached is a patch against 2.6.18 to fix them.

Thanks Bryce.

I will apply is as soon as I get the kbuild.git tree in proper shape
for 2.6.19.

	Sam
_______________________________________________
Kernel-janitors mailing list
Kernel-janitors@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/kernel-janitors

Re: [KJ] [PATCH] Fix for some typos in Documentation/makefiles.txt

[Bryce Harrington]

On Wed, Sep 20, 2006 at 11:10:25PM +0200, Sam Ravnborg wrote:
> On Wed, Sep 20, 2006 at 12:43:37PM -0700, Bryce Harrington wrote:
> > Hi Kai,
> > 
> > I noticed a few typos while reading makefiles.txt to learn about the
> > kbuild system.  Attached is a patch against 2.6.18 to fix them.
> 
> Thanks Bryce.
> 
> I will apply is as soon as I get the kbuild.git tree in proper shape
> for 2.6.19.
> 
> 	Sam

Great, thanks.  If you don't mind, I also have a question about kbuild...

For automated kernel testing when we wish to customize a config, such as
iterating through memory models, tuning settings, experimental features,
etc. we can do this through simple substitutions.

However, this doesn't handle dependencies, such as if choice of a given
memory model should alter other config settings.

Do you know of a tool or technique which can be used from the
commandline to alter an arbitrary symbol's value in a given .config
file, and cascade the change to any dependent symbols, using a given
kernel Kconfig?

From what I have gathered, there is no such thing that does exactly
this; do you know if this is true?

Bryce


_______________________________________________
Kernel-janitors mailing list
Kernel-janitors@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/kernel-janitors

Re: [KJ] [PATCH] Fix for some typos in Documentation/makefiles.txt

[Sam Ravnborg]

> For automated kernel testing when we wish to customize a config, such as
> iterating through memory models, tuning settings, experimental features,
> etc. we can do this through simple substitutions.
> 
> However, this doesn't handle dependencies, such as if choice of a given
> memory model should alter other config settings.
> 
> Do you know of a tool or technique which can be used from the
> commandline to alter an arbitrary symbol's value in a given .config
> file, and cascade the change to any dependent symbols, using a given
> kernel Kconfig?
> 
> From what I have gathered, there is no such thing that does exactly
> this; do you know if this is true?
Unfortunately correct.
It has been requested several times but noone has come up with
neither a good interface to kconfig to do it, nor a good implmentation
of such thing.

For someone that understands the kconfig datastructures it should be
doable but I at least have failed to get a good grip on it so far.
And Roman Zippel - the kconfig maintainer - has been busy with other stuff
lately and haven't come up with something useful either.

	Sam
_______________________________________________
Kernel-janitors mailing list
Kernel-janitors@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/kernel-janitors

Re: [KJ] [PATCH] Fix for some typos in Documentation/makefiles.txt

[Sam Ravnborg]

On Wed, Sep 20, 2006 at 12:43:37PM -0700, Bryce Harrington wrote:
> Hi Kai,
> 
> I noticed a few typos while reading makefiles.txt to learn about the
> kbuild system.  Attached is a patch against 2.6.18 to fix them.
Fixed up, removed trailing whitespace in all of the file and applied.

	Sam
_______________________________________________
Kernel-janitors mailing list
Kernel-janitors@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/kernel-janitors

Re: [KJ] [PATCH] Fix for some typos in Documentation/makefiles.txt

[Bryce Harrington]

On Sun, Sep 24, 2006 at 10:43:06AM +0200, Sam Ravnborg wrote:
> On Wed, Sep 20, 2006 at 12:43:37PM -0700, Bryce Harrington wrote:
> > Hi Kai,
> > 
> > I noticed a few typos while reading makefiles.txt to learn about the
> > kbuild system.  Attached is a patch against 2.6.18 to fix them.
> Fixed up, removed trailing whitespace in all of the file and applied.
> 
> 	Sam

Excellent, thanks.

> > Do you know of a tool or technique which can be used from the
> > commandline to alter an arbitrary symbol's value in a given .config
> > file, and cascade the change to any dependent symbols, using a given
> > kernel Kconfig?  From what I have gathered, there is no such thing
> > that does exactly this; do you know if this is true?
>
> Unfortunately correct.  It has been requested several times but noone
> has come up with neither a good interface to kconfig to do it, nor a
> good implmentation of such thing.
>
> For someone that understands the kconfig datastructures it should be
> doable but I at least have failed to get a good grip on it so far.  And
> Roman Zippel - the kconfig maintainer - has been busy with other stuff
> lately and haven't come up with something useful either.

Given that the symbol portion of the kconfig data structures seem to be
the key piece to understand for this, I wrote some documentation for the
portion I was able to understand.  Hopefully this could serve as a
starting point for something better...

Bryce

Signed-off-by:  Bryce Harrington <bryce@osdl.org>
Applies-to:     linux-2.6.18

--- linux-2.6.18-vanilla/scripts/kconfig/symbol.c	2006-09-19 20:42:06.000000000 -0700
+++ linux-2.6.18/scripts/kconfig/symbol.c	2006-09-24 23:32:58.000000000 -0700
@@ -42,6 +42,12 @@
 	prop->expr = expr_alloc_symbol(sym_lookup(def, 1));
 }
 
+/**
+ * sym_init - Creates several of the root symbols in symbol_hash,
+ * including symbols for ARCH, KERNEL_VERSION, and UNAME_RELEASE,
+ * defaulting the values to the respective environment variables,
+ * if set.
+ */
 void sym_init(void)
 {
 	struct symbol *sym;
@@ -75,6 +81,9 @@
 	sym_add_default(sym, uts.release);
 }
 
+/**
+ * sym_get_type - returns the type for @sym.
+ */
 enum symbol_type sym_get_type(struct symbol *sym)
 {
 	enum symbol_type type = sym->type;
@@ -88,6 +97,10 @@
 	return type;
 }
 
+/**
+ * sym_type_name - converts @type from a symbol_type to the appropriate
+ * string version.  Returns "???" if it doesn't recognize @type.
+ */
 const char *sym_type_name(enum symbol_type type)
 {
 	switch (type) {
@@ -109,6 +122,9 @@
 	return "???";
 }
 
+/**
+ * Returns the first choice property in @sym
+ */
 struct property *sym_get_choice_prop(struct symbol *sym)
 {
 	struct property *prop;
@@ -118,6 +134,10 @@
 	return NULL;
 }
 
+/**
+ * sym_get_default_prop - Returns the first default property in
+ * @sym that has its visible tri-state set to something other than no.
+ */
 struct property *sym_get_default_prop(struct symbol *sym)
 {
 	struct property *prop;
@@ -130,6 +150,10 @@
 	return NULL;
 }
 
+/**
+ * sym_get_range_prop - Returns the first range property in @sym
+ * that has its visible tri-state set to something other than no.
+ */
 struct property *sym_get_range_prop(struct symbol *sym)
 {
 	struct property *prop;
@@ -260,6 +284,11 @@
 	return NULL;
 }
 
+/**
+ * sym_calc_value - recalculates the value for @sym based on its type,
+ * including the symbol's visibility.  Sets values to defaults if 
+ * called recursively.
+ */
 void sym_calc_value(struct symbol *sym)
 {
 	struct symbol_value newval, oldval;
@@ -372,6 +401,10 @@
 	}
 }
 
+/**
+ * sym_clear_all_valid - Clears the SYMBOL_VALID flag for all symbols.
+ * Also causes sym_calc_value() to run on module symbols, if appropriate.
+ */
 void sym_clear_all_valid(void)
 {
 	struct symbol *sym;
@@ -384,6 +417,10 @@
 		sym_calc_value(modules_sym);
 }
 
+/**
+ * sym_set_changed - Marks a given symbol @sym as changed, and
+ * marks all of its sub-properties with the MENU_CHANGED flag.
+ */
 void sym_set_changed(struct symbol *sym)
 {
 	struct property *prop;
@@ -395,6 +432,10 @@
 	}
 }
 
+/**
+ * sym_set_all_changed - Flags all symbols with SYMBOL_CHANGED,
+ * and marks all properties of all symbols as MENU_CHANGED.
+ */
 void sym_set_all_changed(void)
 {
 	struct symbol *sym;
@@ -404,6 +445,11 @@
 		sym_set_changed(sym);
 }
 
+/**
+ * sym_tristate_within_range - checks if @val is an acceptable value
+ * for symbol, returning false if it is not.  @sym must be visible
+ * and either type S_TRISTATE or S_BOOLEAN.
+ */
 bool sym_tristate_within_range(struct symbol *sym, tristate val)
 {
 	int type = sym_get_type(sym);
@@ -423,6 +469,13 @@
 	return val >= sym->rev_dep.tri && val <= sym->visible;
 }
 
+/**
+ * sym_set_tristate_value - Sets @sym to the tristate value @val, returning
+ * false if it could not be set.  @val must be a valid setting for @sym.
+ *
+ * If @sym has a choice type of value, then other symbols will get flagged
+ * SYMBOL_NEW, as appropriate.
+ */
 bool sym_set_tristate_value(struct symbol *sym, tristate val)
 {
 	tristate oldval = sym_get_tristate_value(sym);
@@ -567,6 +620,14 @@
 	}
 }
 
+/**
+ * sym_set_string_value - Sets @sym's value to @newval, returning false
+ * if the value could not be set.  If @sym is of type boolean, then only
+ * characters in "yYnN" are accepted; if @sym is of type tristate, then
+ * characters in "yYnNmM" are accepted.
+ *
+ * This also causes all SYMBOL_VALID flags to be cleared.
+ */
 bool sym_set_string_value(struct symbol *sym, const char *newval)
 {
 	const char *oldval;
@@ -616,6 +677,10 @@
 	return true;
 }
 
+/**
+ * sym_get_string_value - Returns a string version of @sym's current
+ * value.  For boolean or tristate symbols, this is 'n', 'm', or 'y'.
+ */
 const char *sym_get_string_value(struct symbol *sym)
 {
 	tristate val;
@@ -644,6 +709,11 @@
 	return sym->visible > sym->rev_dep.tri;
 }
 
+/**
+ * sym_lookup - gets the symbol object matching the string @name and
+ * indicator @isconst.  Creates a new symbol if one doesn't already 
+ * exist in symbol_hash, and adds it to the hash.
+ */
 struct symbol *sym_lookup(const char *name, int isconst)
 {
 	struct symbol *symbol;
@@ -689,6 +759,11 @@
 	return symbol;
 }
 
+/**
+ * sym_find - returns a symbol for @name.  'y', 'm', and 'n'
+ * return symbol_yes, symbol_mod, and symbol_no, respectively,
+ * while other @name's are looked up in symbol_hash.
+ */
 struct symbol *sym_find(const char *name)
 {
 	struct symbol *symbol = NULL;
@@ -828,6 +903,11 @@
 	return sym2;
 }
 
+/**
+ * prop_alloc - Allocates and returns a property object for the 
+ * symbol @sym, of type @type.  Also appends the new property to
+ * the symbol's property list.
+ */
 struct property *prop_alloc(enum prop_type type, struct symbol *sym)
 {
 	struct property *prop;
@@ -858,6 +938,10 @@
 	return NULL;
 }
 
+/**
+ * prop_get_type_name - Returns a string version of the property type
+ * @type, such as 'prompt', 'menu', 'select', etc.
+ */
 const char *prop_get_type_name(enum prop_type type)
 {
 	switch (type) {

_______________________________________________
Kernel-janitors mailing list
Kernel-janitors@lists.osdl.org
https://lists.osdl.org/mailman/listinfo/kernel-janitors