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>

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