Various Kconfig fixes and improvements:

 - Add helps texts to multiple user-visible Kconfig options.

 - Improve some menu and option names.

 - PAYLOAD_NONE should come before PAYLOAD_ELF, so that you scroll down
   (instead of up) when changing "no payload" to "ELF payload" (more
   intuitive, IMHO).

 - s/cbfs/cbfstool/.

 - Add some TODO items where needed.

 - Put GDB_STUB in a "Debugging" menu, no options should be top-level.
   There'll be more debug options later, I'm pretty sure.

 - Start converting help texts which are not user-visible to #-comments.

 - Re-order some options for more intuitive menus.

 - Set ARCH_X86 and ARCH_POWERPC to "default n", each boards selects them.

 - "Maximum reboot count" should proabably not be user-selectable, or at
   most if CONFIG_EXPERT (yet to be added) is enabled. It does definately
   not need its own "Misc options" menu.

 - Set PCI_ROM_RUN and VGA_ROM_RUN to "default y", most users will want to
   run option ROMs.

Signed-off-by: Uwe Hermann <uwe@hermann-uwe.de>
Acked-by: Uwe Hermann <uwe@hermann-uwe.de>



git-svn-id: svn://svn.coreboot.org/coreboot/trunk@4734 2b7e53f0-3cfb-0310-b3e9-8179ed1497e1

6 files changed, 155 insertions, 73 deletions

diff --git a/src/Kconfig b/src/Kconfig
index 273d770a5f..6458037497 100644
--- a/src/Kconfig
+++ b/src/Kconfig
@@ -30,10 +30,15 @@ mainmenu "Coreboot Configuration"
 menu "General setup"
 
 config LOCALVERSION
-	string "Local version - append to coreboot release"
+	string "Local version string"
 	help
 	  Append an extra string to the end of the coreboot version.
 
+	  This can be useful if, for instance, you want to append the
+	  respective board's hostname or some other identifying string to
+	  the coreboot version number, so that you can easily distinguish
+	  boot logs of different boards from each other.
+
 endmenu
 
 source src/mainboard/Kconfig
@@ -225,10 +230,10 @@ config GFXUMA
 
 # TODO
 # menu "Drivers"
-# 
+#
 # endmenu
 
-menu "Generated System Tables"
+menu "System tables"
 
 config HAVE_LOW_TABLES
 	bool
@@ -239,7 +244,7 @@ config HAVE_HIGH_TABLES
 	default y
 
 config MULTIBOOT
-	bool "Add Multiboot tables (for grub2)"
+	bool "Generate Multiboot tables (for GRUB2)"
 	default n
 
 config HAVE_ACPI_TABLES
@@ -258,16 +263,22 @@ endmenu
 
 menu "Payload"
 
-config COMPRESSED_PAYLOAD_LZMA
-	bool "Use LZMA compression for payloads"
-	default yes
-
 choice
-	prompt "Payload type"
+	prompt "Add a payload"
 	default PAYLOAD_NONE
 
+config PAYLOAD_NONE
+	bool "None"
+	help
+	  Select this option if you want to create an "empty" coreboot
+	  ROM image for a certain mainboard, i.e. a coreboot ROM image
+	  which does not yet contain a payload.
+
+	  For such an image to be useful, you have to use 'cbfstool'
+	  to add a payload to the ROM image later.
+
 config PAYLOAD_ELF
-	bool "An ELF executable payload file"
+	bool "An ELF executable payload"
 	help
 	  Select this option if you have a payload image (an ELF file)
 	  which coreboot should run as soon as the basic hardware
@@ -275,15 +286,6 @@ config PAYLOAD_ELF
 
 	  You will be able to specify the location and file name of the
 	  payload image later.
-config PAYLOAD_NONE
-	bool "No payload"
-	help
-	  Select this option if you want to create an "empty" coreboot
-	  ROM image for a certain mainboard, i.e. a coreboot ROM image
-	  which does not yet contain a payload.
-
-	  For such an image to be useful, you have to use the 'cbfs' tool
-	  to add a payload to the ROM image later.
 
 endchoice
 
@@ -294,6 +296,15 @@ config FALLBACK_PAYLOAD_FILE
 	help
 	  The path and filename of the ELF executable file to use as payload.
 
+# TODO: Defined if no payload? Breaks build?
+config COMPRESSED_PAYLOAD_LZMA
+	bool "Use LZMA compression for payloads"
+	default y
+	depends on PAYLOAD_ELF
+	help
+	  In order to reduce the size payloads take up in the ROM chip
+	  coreboot can compress them using the LZMA algorithm.
+
 endmenu
 
 menu "VGA BIOS"
@@ -319,11 +330,20 @@ config FALLBACK_VGA_BIOS_ID
 	depends on VGA_BIOS
 	default "1106,3230"
 	help
-	  The ID that would associate your VGA BIOS to your video card.
-	  (PCI VendorID, PCI Device ID)
+	  The comma-separated PCI vendor and device ID that would associate
+	  your VGA BIOS to your video card.
+
+	  Example: 1106,3230
+
+	  In the above example 1106 is the PCI vendor ID (in hex, but without
+	  the "0x" prefix) and 3230 specifies the PCI device ID of the
+	  video card (also in hex, without "0x" prefix).
 
 endmenu
 
+menu "Debugging"
+
+# TODO: Better help text and detailed instructions.
 config GDB_STUB
 	bool "GDB debugging support"
 	default y
@@ -331,3 +351,5 @@ config GDB_STUB
 	  If enabled, you will be able to set breakpoints for gdb debugging.
 	  See src/arch/i386/lib/c_start.S for details.
 
+endmenu
+
diff --git a/src/arch/i386/Kconfig b/src/arch/i386/Kconfig
index 2e2f650f06..8481cf6f06 100644
--- a/src/arch/i386/Kconfig
+++ b/src/arch/i386/Kconfig
@@ -1,23 +1,22 @@
+# This option is used to set the architecture of a mainboard to X86.
+# It is usually set in mainboard/*/Kconfig.
 config ARCH_X86
 	bool
-	help
-	  This option is used to set the architecture of a mainboard.
-	  It is usually set in mainboard/*/Kconfig.
+	default n
 
+# This is an SMP option. It relates to starting up APs.
+# It is usually set in mainboard/*/Kconfig.
+# TODO: Improve description.
 config AP_IN_SIPI_WAIT
 	bool
 	default n
 	depends on ARCH_X86
-	help
-	  This is an SMP option. It relates to starting up APs. 
-	  It is usually set in mainboard/*/Kconfig.
 
+# This is the name of the respective architecture subdirectory in arch/.
 config ARCH
 	string
 	default i386
 	depends on ARCH_X86
-	help
-	  This is the name of the respective subdirectory in arch/.
 
 config ROMBASE
 	hex
@@ -58,11 +57,9 @@ config STACK_SIZE
 	hex
 	default 0x8000
 
-menu "Misc options"
-
+# Maximum reboot count
+# TODO: Improve description.
 config MAX_REBOOT_CNT
-	int "Maximum reboot count"
+	int
 	default 3
 
-endmenu
-
diff --git a/src/arch/ppc/Kconfig b/src/arch/ppc/Kconfig
index 66a90515fb..1916433f9e 100644
--- a/src/arch/ppc/Kconfig
+++ b/src/arch/ppc/Kconfig
@@ -1,13 +1,12 @@
+# This option is used to set the architecture of a mainboard to PowerPC.
+# It is usually set in mainboard/*/Kconfig.
 config ARCH_POWERPC
 	bool
-	help
-	  This option is used to set the architecture of a mainboard.
-	  It is usually set in mainboard/*/Kconfig.
+	default n
 
+# This is the name of the respective architecture subdirectory in arch/.
 config ARCH
 	string
 	default ppc
 	depends on ARCH_POWERPC
-	help
-	  This is the name of the respective subdirectory in arch/.
 
diff --git a/src/console/Kconfig b/src/console/Kconfig
index 697e3587fe..2bdffc1aff 100644
--- a/src/console/Kconfig
+++ b/src/console/Kconfig
@@ -1,53 +1,96 @@
 menu "Console options"
 
+# TODO: Rename to SERIAL_CONSOLE once Kconfig transition is complete.
 config CONSOLE_SERIAL8250
-	#TODO Rename to SERIAL_CONSOLE once Kconfig transition is complete.
-	bool "See output on the serial port console"
+	bool "Enable serial port console output"
 	default y
+	help
+	  Send coreboot debug output to a serial port console.
 
-config SERIAL_POST
-	bool "See POST output on the serial port console"
-	default n
-
+# TODO: COM1, COM2 etc.
 config TTYS0_BASE
 	hex "I/O base for the serial port"
 	depends on CONSOLE_SERIAL8250
 	default 0x3f8
 
 config SERIAL_SET_SPEED
-	bool "Override the serial console BAUD rate"
+	bool "Override the serial port BAUD rate"
 	default y
 	depends on CONSOLE_SERIAL8250
 
 config TTYS0_BAUD
-	int "Serial console BAUD rate"
+	int "Serial port BAUD rate"
 	depends on SERIAL_SET_SPEED
 	default 115200
 
+# TODO: Allow user-friendly selection of settings other than 8n1.
 config TTYS0_LCS
 	int
 	default 3
 	depends on CONSOLE_SERIAL8250
 
+config SERIAL_POST
+	bool "Enable POST output on the serial port console"
+	depends on CONSOLE_SERIAL8250
+	default n
+	help
+	  If enabled, coreboot will additionally print POST codes (which are
+	  usually displayed using a so-called "POST card" ISA/PCI/PCI-E
+	  device) on the serial console.
+
+# TODO: FIX DEPENDENCY HERE
 config USBDEBUG_DIRECT
-	bool "USB debug dongle support. Not supported on all chipsets."
+	bool "USB 2.0 EHCI debug dongle support"
 	default n
-	# TODO: FIX DEPENDENCY HERE
+	help
+	  This option allows you to use a so-called USB EHCI Debug device
+	  to retrieve the coreboot debug messages (instead, or in addition
+	  to, a serial port).
+
+	  This feature is NOT supported on all chipsets in coreboot!
+
+	  It also requires a USB2 controller which supports the EHCI
+	  Debug Port capability. Controllers which are known to work:
+	
+	    * 10b9:5239 ALi Corporation USB 2.0 (USB PCI card)
+	    * 8086:24cd Intel ICH4/ICH4-M
+	    * 8086:24dd Intel ICH5
+	    * 8086:265c Intel ICH6
+	    * 8086:268c Intel 631xESB/632xESB/3100
+	    * 8086:27cc Intel ICH7
+	    * 8086:2836 Intel ICH8
+	    * 8086:283a Intel ICH8
+	    * 8086:293a Intel ICH9
+	    * 10de:0088 NVIDIA MCP2A
+	    * 10de:005b NVIDIA CK804
+	    * 10de:026e NVIDIA MCP51
+	    * 10de:036d NVIDIA MCP55
+	    * 10de:03f2 NVIDIA MCP61
+	    * 1002:4386 ATI/AMD SB600
+	    * 1106:3104 VIA VX800
+
+	  See http://www.coreboot.org/EHCI_Debug_Port for an up-to-date list.
 
 config CONSOLE_VGA
-	bool "Use VGA console, once initialized."
+	bool "Use VGA console once initialized"
 	default n
 
+# TODO: Deps?
+# TODO: Improve description.
 config CONSOLE_VGA_ONBOARD_AT_FIRST
-	bool "Use onboard VGA as primary"
+	bool "Use onboard VGA as primary video device"
 	default n
 	help
 	  If not selected, the last adapter found will be used.
 
+# TODO: User-friendly "choice" selection.
+# TODO: Add help text.
 config MAXIMUM_CONSOLE_LOGLEVEL
 	int "Maximum console loglevel"
 	default 9
 
+# TODO: User-friendly "choice" selection.
+# TODO: Add help text.
 config DEFAULT_CONSOLE_LOGLEVEL
 	int "Default console loglevel"
 	default 9
diff --git a/src/devices/Kconfig b/src/devices/Kconfig
index 173ae9df94..1bfd2d289b 100644
--- a/src/devices/Kconfig
+++ b/src/devices/Kconfig
@@ -24,43 +24,58 @@ config VGA_BRIDGE_SETUP
 	bool "Setup bridges on path to VGA adapter"
 	default y
 	help
-	  Allow bridges to set up legacy decoding ranges for VGA.  Don't disable
+	  Allow bridges to set up legacy decoding ranges for VGA. Don't disable
 	  this unless you're sure you don't want the briges setup for VGA.
 
+# TODO: Explain differences (if any) for onboard cards.
 config VGA_ROM_RUN
-	bool "Run VGA Option ROMs"
+	bool "Run VGA option ROMs"
+	default y
 	help
-	  Execute VGA option ROMs if found. This is required to enable PCI/AGP
-	  VGA plugin cards.
+	  Execute VGA option ROMs, if found. This is required to enable
+	  PCI/AGP/PCI-E video cards.
 
 config PCI_ROM_RUN
-	bool "Run non-VGA Option ROMs"
+	bool "Run non-VGA option ROMs"
+	default y
 	help
-	  Execute non-VGA PCI option ROMs if found.
+	  Execute non-VGA PCI option ROMs, if found.
+
+	  Examples include IDE/SATA controller option ROMs and option ROMs
+	  for network cards (NICs).
 
+# TODO: Describe YABEL vs. x86emu differences in more detail.
 choice
-	prompt "Option ROM Execution"
-	default  PCI_OPTION_ROM_RUN_REALMODE
+	prompt "Option ROM execution type"
+	default PCI_OPTION_ROM_RUN_REALMODE
 	depends on PCI_ROM_RUN || VGA_ROM_RUN
+
+config PCI_OPTION_ROM_RUN_REALMODE
+	prompt "Real mode"
+	bool
 	help
-	  You can choose to execute PCI option ROMs natively (32bit x86 system
-	  required) or in an emulator (x86emu or YABEL).
+	  If you select this option, PCI option ROMs will be executed
+	  natively on the hardware (a 32bit x86 system is required).
 
-	config PCI_OPTION_ROM_RUN_REALMODE
-		prompt "Real mode"
-		bool
+config PCI_OPTION_ROM_RUN_YABEL
+	prompt "YABEL"
+	bool
+	help
+	  If you select this option, the YABEL BIOS emulator will be used to
+	  execute PCI option ROMs.
 
-	config PCI_OPTION_ROM_RUN_YABEL
-		prompt "YABEL"
-		bool
+config PCI_OPTION_ROM_RUN_X86EMU
+	prompt "x86emu"
+	bool
+	help
+	  If you select this option, the x86emu BIOS emulator will be used to
+	  execute PCI option ROMs.
 
-	config PCI_OPTION_ROM_RUN_X86EMU
-		prompt "X86EMU"
-		bool
 endchoice
 
+# TODO: Describe better, and/or make a "choice" selection for this.
 config YABEL_DEBUG_FLAGS
-	prompt "Hex value for debug flags"
+	prompt "Hex value for YABEL debug flags"
 	hex
 	default 0x0
 	depends on PCI_OPTION_ROM_RUN_YABEL
diff --git a/src/mainboard/Kconfig b/src/mainboard/Kconfig
index 9f7f8e42d5..a96b42a986 100644
--- a/src/mainboard/Kconfig
+++ b/src/mainboard/Kconfig
@@ -370,9 +370,15 @@ source "src/mainboard/thomson/Kconfig"
 source "src/mainboard/tyan/Kconfig"
 source "src/mainboard/via/Kconfig"
 
+# TODO: No help text possible for choice fields?
 choice
 	prompt "ROM chip size"
 	default COREBOOT_ROMSIZE_KB_256
+	help
+	  Select the size of the ROM chip you intend to flash coreboot on.
+
+	  The build system will take care of creating a coreboot.rom file
+	  of the matching size.
 
 config COREBOOT_ROMSIZE_KB_128
 	bool "128 KB"
@@ -406,6 +412,7 @@ config COREBOOT_ROMSIZE_KB_4096
 
 endchoice
 
+# Map the config names to an integer (KB).
 config COREBOOT_ROMSIZE_KB
 	int
 	default 128 if COREBOOT_ROMSIZE_KB_128
@@ -414,9 +421,8 @@ config COREBOOT_ROMSIZE_KB
 	default 1024 if COREBOOT_ROMSIZE_KB_1024
 	default 2048 if COREBOOT_ROMSIZE_KB_2048
 	default 4096 if COREBOOT_ROMSIZE_KB_4096
-	help
-	  Map the config names to an integer.
 
+# Map the config names to a hex value (bytes).
 config ROM_SIZE
 	hex
 	default 0x20000 if COREBOOT_ROMSIZE_KB_128