summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMartin Roth <martinroth@google.com>2016-01-25 20:10:14 -0700
committerMartin Roth <martinroth@google.com>2016-01-30 17:29:40 +0100
commitb5400ad412e1c8e6dba7d9f25d3eb7a5ba96d193 (patch)
treee9387df846a6539aec8846bf8386a56494635345
parent08cf90f860604b4ef26d4740ae985f550f6bad90 (diff)
downloadcoreboot-b5400ad412e1c8e6dba7d9f25d3eb7a5ba96d193.tar.xz
kconfig_lint: Add readme document
The readme describes the operation and usage of kconfig_lint. It also lists all the notes, warnings, and errors that kconfig_lint looks for. Change-Id: I873f394ff93fce42cd9638cbbad6134f1aef3a6a Signed-off-by: Martin Roth <martinroth@google.com> Reviewed-on: https://review.coreboot.org/13464 Tested-by: build bot (Jenkins) Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
-rw-r--r--util/lint/kconfig_lint_README97
1 files changed, 97 insertions, 0 deletions
diff --git a/util/lint/kconfig_lint_README b/util/lint/kconfig_lint_README
new file mode 100644
index 0000000000..9076f4ca41
--- /dev/null
+++ b/util/lint/kconfig_lint_README
@@ -0,0 +1,97 @@
+kconfig_lint is a tool to help identify issues within coreboot's Kconfig
+files. It is very specific to coreboot, and is not intended to be used as a
+generic Kconfig lint tool for other projects.
+
+Operation:
+kconfig_lint parses the entire kconfig tree, building up a hash table of all
+of the statements. It then searches the coreboot tree looking for all usage of
+any Kconfig symbols. By combining these two, it is able to find many issues
+that would be difficult to locate otherwise.
+
+Usage:
+kconfig_lint <options>
+ -o|--output=file Set output filename
+ -p|--print Print full output
+ -e|--errors_off Don't print warnings or errors
+ -w|--warnings_off Don't print warnings
+ -n|--notes Show minor notes
+ -G|--no_git_grep Use standard grep tools instead of git grep
+
+
+Options:
+ -o|--output=file Send the output to a file instead of printing to stdout.
+
+ -p|--print Shows the entire Kconfig tree as parsed by kconfig_lint,
+ including the filename and line number of each statement.
+ This can be very helpful for debugging Kconfig issues.
+
+ -e|--errors_off Suppress both error and warning output. Useful along with
+ the --print command
+
+-w|--warnings_off Suppress warning output
+
+-n|--notes Enable the display of minor notes that kconfig_lint has
+ found. These might be issues, but probably are not.
+
+ -G|--no_git_grep Instead of using the 'git grep' command, use regular grep.
+ This is useful for checking coreboot trees that are not
+ contained in a git repo.
+
+Issues that kconfig_lint checks for:
+
+Notes:
+- Show when the range set for a hex or int does not match a previous range
+
+Warnings in Kconfig files:
+- Any 'default' expressions that can never be reached.
+- Symbols that are defined but never used.
+- Help text starting with no whitespace.
+- Directories specified in a 'source' keyword do not exist.
+- A 'source' keyword loading a Kconfig file that has already been loaded.
+- A 'source' keyword loading a Kconfig file that doesn't exist. Note that
+ globs are excluded from this check.
+
+Warnings in coreboot source files:
+- #define of Kconfig symbol - Symbols should only be defined in Kconfig.
+- #define starting with 'CONFIG_' - these should be reserved for Kconfig
+ symbols.
+- 'IS_ENABLED()' block that could not be interpreted.
+- Kconfig files that are not loaded by a 'source' keyword.
+
+Errors in Kconfig files:
+- Selects do not work on symbols created in a choice block.
+- All symbols used in selects or expressions must be defined in a config
+ statement.
+- 'endchoice' keyword not used in a choice block
+- Choice block defined with no symbols.
+- The 'tristate' type is not used in coreboot.
+- A 'select' keyword used outside of a config block.
+- Symbols created both inside and outside of a choice block.
+- A 'range' keyword has higher minimum than maximum value.
+- A config block with a prompt at the top level (the top level is currently
+ just for menus).
+- Indentation using spaces instead of tabs. We indent using tabs, although
+ the tab may be followed by spaces, particularly for help blocks.
+- Lines not ending with a linefeed. These can cause some keywords to not
+ function properly ('source' keywords in particular). It's also just
+ generally good to end the file with a linefeed.
+
+Errors in Kconfig that are also caught by Kconfig itself:
+- Invalid expressions.
+- Unrecognized keywords.
+- An 'optional' keyword used outside of a choice block
+- The 'select' keyword only works on bool symbols.
+- A 'range' keyword used outside of a config block.
+- A 'default' keyword used outside of a config or choice block.
+- Symbol types must be consistent - they cannot be bool in one location and
+ int in another location.
+- Type keywords (bool, int, hex, string) used outside of a config block.
+- Using a 'prompt' keyword not inside a config or choice block.
+
+Errors in coreboot source files:
+- '#ifdef' or '#if defined' used on bool, int, or hex - these are always
+ defined in coreboot's version of Kconfig.
+- The IS_ENABLED macro is only valid for bool symbols.
+- The IS_ENABLED used on unknown CONFIG_ value, like an obsolete symbol.
+
+TODO: check for choice entries at the top level