util/lint/kconfig_lint_README

   1 kconfig_lint is a tool to help identify issues within coreboot's Kconfig
   2 files.  It is very specific to coreboot, and is not intended to be used as a
   3 generic Kconfig lint tool for other projects.
   4
   5 Operation:
   6 kconfig_lint parses the entire kconfig tree, building up a hash table of all
   7 of the statements.  It then searches the coreboot tree looking for all usage of
   8 any Kconfig symbols.  By combining these two, it is able to find many issues
   9 that would be difficult to locate otherwise.
  10
  11 Usage:
  12 kconfig_lint <options>
  13  -o|--output=file    Set output filename
  14  -p|--print          Print full output
  15  -e|--errors_off     Don't print warnings or errors
  16  -w|--warnings_off   Don't print warnings
  17  -n|--notes          Show minor notes
  18  -G|--no_git_grep    Use standard grep tools instead of git grep
  19
  20
  21 Options:
  22  -o|--output=file    Send the output to a file instead of printing to stdout.
  23
  24  -p|--print          Shows the entire Kconfig tree as parsed by kconfig_lint,
  25                      including the filename and line number of each statement.
  26                      This can be very helpful for debugging Kconfig issues.
  27
  28  -e|--errors_off     Suppress both error and warning output.  Useful along with
  29                      the --print command
  30
  31 -w|--warnings_off    Suppress warning output
  32
  33 -n|--notes           Enable the display of minor notes that kconfig_lint has
  34                      found.  These might be issues, but probably are not.
  35
  36  -G|--no_git_grep    Instead of using the 'git grep' command, use regular grep.
  37                      This is useful for checking coreboot trees that are not
  38                      contained in a git repo.
  39
  40 Issues that kconfig_lint checks for:
  41
  42 Notes:
  43 - Show when the range set for a hex or int does not match a previous range
  44
  45 Warnings in Kconfig files:
  46 - Symbols that are defined but never used.
  47 - A 'source' keyword loading a Kconfig file that has already been loaded.
  48 - A 'source' keyword loading a Kconfig file that doesn't exist. Note that
  49   globs are excluded from this check.
  50
  51 Warnings in coreboot source files:
  52 - Kconfig files that are not loaded by a 'source' keyword.
  53 - Naked use of boolean CONFIG_XXX Kconfig in C that's not wrapped in CONFIG()
  54
  55 Errors in Kconfig files:
  56 - Any 'default' expressions that can never be reached.
  57 - Directories specified in a 'source' keyword do not exist.
  58 - Selects do not work on symbols created in a choice block.
  59 - All symbols used in selects or expressions must be defined in a config
  60   statement.
  61 - 'endchoice' keyword not used in a choice block
  62 - Choice block defined with no symbols.
  63 - The 'tristate' type is not used in coreboot.
  64 - A 'select' keyword used outside of a config block.
  65 - Symbols created both inside and outside of a choice block or in two
  66   different choice blocks.
  67 - A 'range' keyword has higher minimum than maximum value.
  68 - A config block with a prompt at the top level (the top level is currently
  69   just for menus).
  70 - Indentation using spaces instead of tabs.  We indent using tabs, although
  71   the tab may be followed by spaces, particularly for help blocks.
  72 - Lines not ending with a linefeed.  These can cause some keywords to not
  73   function properly ('source' keywords in particular).  It's also just
  74   generally good to end the file with a linefeed.
  75 - Help text starting with no whitespace.
  76 - Help text that starts at the same indentation level as the 'help' keyword.
  77
  78 Errors in Kconfig that are also caught by Kconfig itself:
  79 - Invalid expressions.
  80 - Unrecognized keywords.
  81 - An 'optional' keyword used outside of a choice block
  82 - The 'select' keyword only works on bool symbols.
  83 - A 'range' keyword used outside of a config block.
  84 - A 'default' keyword used outside of a config or choice block.
  85 - Symbol types must be consistent - they cannot be bool in one location and
  86   int in another location.
  87 - Type keywords (bool, int, hex, string) used outside of a config block.
  88 - Using a 'prompt' keyword not inside a config or choice block.
  89 - Symbols with no defined type.
  90
  91 Errors in coreboot source files:
  92 - #define of Kconfig symbol - Symbols should only be defined in Kconfig.
  93 - #define starting with 'CONFIG_' - these should be reserved for Kconfig
  94   symbols.
  95 - '#ifdef' or '#if defined' used on bool, int, or hex - these are always
  96   defined in coreboot's version of Kconfig.
  97 - The CONFIG() macro is only valid for bool symbols.
  98 - CONFIG() used on unknown Kconfig, like an obsolete symbol.
  99 - The deprecated IS_ENABLED() macro is used.
 100
 101 TODO: check for choice entries at the top level