util/lint/kconfig_lint_README

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:
- Symbols that are defined but never used.
- 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:
- Kconfig files that are not loaded by a 'source' keyword.
- Naked use of boolean CONFIG_XXX Kconfig in C that's not wrapped in CONFIG()

Errors in Kconfig files:
- Any 'default' expressions that can never be reached.
- Directories specified in a 'source' keyword do not exist.
- 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 or in two
  different choice blocks.
- 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.
- Help text starting with no whitespace.
- Help text that starts at the same indentation level as the 'help' keyword.

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.
- Symbols with no defined type.

Errors 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.
- '#ifdef' or '#if defined' used on bool, int, or hex - these are always
  defined in coreboot's version of Kconfig.
- The CONFIG() macro is only valid for bool symbols.
- CONFIG() used on unknown Kconfig, like an obsolete symbol.
- The deprecated IS_ENABLED() macro is used.

TODO: check for choice entries at the top level