kconfig: Sync with upstream v4.16

This commit introduces the following upstream changes:

5ae6fcc4bb82 kconfig: fix line number in recursive inclusion error message
1a90ce36c6ef kconfig: Update ncurses package names for menuconfig
bf0bbdcf1003 kconfig: Don't leak choice names during parsing
f4bc1eefc160 kconfig: set SYMBOL_AUTO to the symbol marked with defconfig_list
cd81fc82b93f kconfig: add xstrdup() helper
523ca58b7db2 kconfig: remove const qualifier from sym_expand_string_value()
d717f24d8c68 kconfig: add xrealloc() helper
9e3e10c72536 kconfig: send error messages to stderr
f3ff6fb5db68 kconfig: echo stdin to stdout if either is redirected
d2a04648a5db kconfig: remove check_stdin()
cd58a91def2a kconfig: remove 'config*' pattern from .gitignnore
4f208f392103 kconfig: show '?' prompt even if no help text is available
cb67ab2cd2b8 kconfig: do not write choice values when their dependency becomes n
1b9eda2e4892 kconfig: Warn if help text is blank
cedd55d49dee kconfig: Remove silentoldconfig from help and docs; fix kconfig/conf's help
1ccb27143360 kconfig: make "Selected by:" and "Implied by:" readable
312ee68752fa kconfig: announce removal of oldnoconfig if used
d0fd0428ecf0 kconfig: fix make xconfig when gettext is missing
b53688014e33 kconfig: Clarify menu and 'if' dependency propagation
9d1a9e8bc18b kconfig: Document 'if' flattening logic
d3465af60f44 kconfig: Clarify choice dependency propagation
3e41ba05b6d6 kconfig: Document SYMBOL_OPTIONAL logic
765f4cdef6f8 kconfig: use default 'yy' prefix for lexer and parser
84dd95d4f87a kconfig: make conf_unsaved a local variable of conf_read()
5a3dc717b3c7 kconfig: make xfgets() really static
52e58a3caeba kconfig: make input_mode static
6479f327dea6 kconfig: Warn if there is more than one help text
b92d804a5179 kconfig: drop 'boolean' keyword
df60f4b92d3d kconfig: Remove menu_end_entry()
0735f7e5def2 kconfig: Document important expression functions
05cccce58045 kconfig: Document automatic submenu creation code
7cf33f88e294 kconfig: Fix choice symbol expression leak
5b1374b3b3c2 kconfig: Fix expr_free() E_NOT leak
ae7440ef0c80 kconfig: Fix automatic menu creation mem leak
0724a7c32a54 kconfig: Don't leak main menus during parsing
bc28fe1d5ede kconfig: Don't leak 'option' arguments during parsing
24161a6711c9 kconfig: Don't leak 'source' filenames during parsing
26e47a3c11a2 kconfig: Don't leak symbol names during parsing
29c833061c1d kconfig: generate lexer and parser during build instead of shipping
e3b03bf29d6b kconfig: display recursive dependency resolution hint just once
f77850d3fe0c kconfig: Clean up modules handling and fix crash
fa8cedaef814 kconfig: Clarify expression rewriting
9a826842ff2f kconfig: Rename menu_check_dep() to rewrite_m()
c873443430eb kconfig: Sync zconf.y with zconf.tab.c_shipped
52aede4ba5ef kconfig: Document the 'symbol' struct
33ca1a248663 kconfig: Document the 'menu' struct
2c37e08464a8 kconfig: Warn if choice default is not in choice

Signed-off-by: Chris Packham <judge.packham@gmail.com>

1 files changed, 90 insertions, 1 deletions

diff --git a/kconfig/expr.h b/kconfig/expr.h
index a73f762..c16e82e 100644
--- a/kconfig/expr.h
+++ b/kconfig/expr.h
@@ -74,17 +74,60 @@ enum {
 	S_DEF_COUNT
 };
 
+/*
+ * Represents a configuration symbol.
+ *
+ * Choices are represented as a special kind of symbol and have the
+ * SYMBOL_CHOICE bit set in 'flags'.
+ */
 struct symbol {
+	/* The next symbol in the same bucket in the symbol hash table */
 	struct symbol *next;
+
+	/* The name of the symbol, e.g. "FOO" for 'config FOO' */
 	char *name;
+
+	/* S_BOOLEAN, S_TRISTATE, ... */
 	enum symbol_type type;
+
+	/*
+	 * The calculated value of the symbol. The SYMBOL_VALID bit is set in
+	 * 'flags' when this is up to date. Note that this value might differ
+	 * from the user value set in e.g. a .config file, due to visibility.
+	 */
 	struct symbol_value curr;
+
+	/*
+	 * Values for the symbol provided from outside. def[S_DEF_USER] holds
+	 * the .config value.
+	 */
 	struct symbol_value def[S_DEF_COUNT];
+
+	/*
+	 * An upper bound on the tristate value the user can set for the symbol
+	 * if it is a boolean or tristate. Calculated from prompt dependencies,
+	 * which also inherit dependencies from enclosing menus, choices, and
+	 * ifs. If 'n', the user value will be ignored.
+	 *
+	 * Symbols lacking prompts always have visibility 'n'.
+	 */
 	tristate visible;
+
+	/* SYMBOL_* flags */
 	int flags;
+
+	/* List of properties. See prop_type. */
 	struct property *prop;
+
+	/* Dependencies from enclosing menus, choices, and ifs */
 	struct expr_value dir_dep;
+
+	/* Reverse dependencies through being selected by other symbols */
 	struct expr_value rev_dep;
+
+	/*
+	 * "Weak" reverse dependencies through being implied by other symbols
+	 */
 	struct expr_value implied;
 };
 
@@ -133,7 +176,7 @@ enum prop_type {
 	P_UNKNOWN,
 	P_PROMPT,   /* prompt "foo prompt" or "BAZ Value" */
 	P_COMMENT,  /* text associated with a comment */
-	P_MENU,     /* prompt associated with a menuconfig option */
+	P_MENU,     /* prompt associated with a menu or menuconfig symbol */
 	P_DEFAULT,  /* default y */
 	P_CHOICE,   /* choice value */
 	P_SELECT,   /* select BAR */
@@ -166,22 +209,67 @@ struct property {
 	for (st = sym->prop; st; st = st->next) \
 		if (st->text)
 
+/*
+ * Represents a node in the menu tree, as seen in e.g. menuconfig (though used
+ * for all front ends). Each symbol, menu, etc. defined in the Kconfig files
+ * gets a node. A symbol defined in multiple locations gets one node at each
+ * location.
+ */
 struct menu {
+	/* The next menu node at the same level */
 	struct menu *next;
+
+	/* The parent menu node, corresponding to e.g. a menu or choice */
 	struct menu *parent;
+
+	/* The first child menu node, for e.g. menus and choices */
 	struct menu *list;
+
+	/*
+	 * The symbol associated with the menu node. Choices are implemented as
+	 * a special kind of symbol. NULL for menus, comments, and ifs.
+	 */
 	struct symbol *sym;
+
+	/*
+	 * The prompt associated with the node. This holds the prompt for a
+	 * symbol as well as the text for a menu or comment, along with the
+	 * type (P_PROMPT, P_MENU, etc.)
+	 */
 	struct property *prompt;
+
+	/*
+	 * 'visible if' dependencies. If more than one is given, they will be
+	 * ANDed together.
+	 */
 	struct expr *visibility;
+
+	/*
+	 * Ordinary dependencies from e.g. 'depends on' and 'if', ANDed
+	 * together
+	 */
 	struct expr *dep;
+
+	/* MENU_* flags */
 	unsigned int flags;
+
+	/* Any help text associated with the node */
 	char *help;
+
+	/* The location where the menu node appears in the Kconfig files */
 	struct file *file;
 	int lineno;
+
+	/* For use by front ends that need to store auxiliary data */
 	void *data;
 };
 
+/*
+ * Set on a menu node when the corresponding symbol changes state in some way.
+ * Can be checked by front ends.
+ */
 #define MENU_CHANGED		0x0001
+
 #define MENU_ROOT		0x0002
 
 struct jump_key {
@@ -222,6 +310,7 @@ struct expr *expr_simplify_unmet_dep(struct expr *e1, struct expr *e2);
 void expr_fprint(struct expr *e, FILE *out);
 struct gstr; /* forward */
 void expr_gstr_print(struct expr *e, struct gstr *gs);
+void expr_gstr_print_revdep(struct expr *e, struct gstr *gs);
 
 static inline int expr_is_yes(struct expr *e)
 {