From b5400ad412e1c8e6dba7d9f25d3eb7a5ba96d193 Mon Sep 17 00:00:00 2001 From: Martin Roth Date: Mon, 25 Jan 2016 20:10:14 -0700 Subject: 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 Reviewed-on: https://review.coreboot.org/13464 Tested-by: build bot (Jenkins) Reviewed-by: Stefan Reinauer --- util/lint/kconfig_lint_README | 97 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 util/lint/kconfig_lint_README (limited to 'util') 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 + -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 -- cgit v1.2.3