[PATCH 0/1] Documentation: kbuild: explicitly document missing prompt

[PATCH 0/1] Documentation: kbuild: explicitly document missing prompt

[Stephen Brennan]

Hi folks,

Recently I was trying to build a kernel with the following options:

CONFIG_KALLSYMS_ABSOLUTE_PERCPU=n
CONFIG_KALLSYMS_BASE_RELATIVE=n

They are defined in init/Kconfig like so:

config KALLSYMS_ABSOLUTE_PERCPU
	bool
	depends on KALLSYMS
	default X86_64 && SMP

config KALLSYMS_BASE_RELATIVE
	bool
	depends on KALLSYMS
	default y

I was banging my head against the wall trying to understand why I couldn't edit
these with any kconfig tool (e.g. make xconfig) and why my edits to the .config
file were getting overwritten. A coworker finally explained to me that the
reason was that the config options did not have a prompt, and so they are not
user configurable. This is a really subtle behavior that was not obvious to me
from the documentation. Though now I understand it, I can see why it's used
widely.

For example, KALLSYMS_ABSOLUTE_PERCPU has no prompt and is only set when
X86_64 && SMP, because it is a trick that allows percpu variables to be encoded
while still only using 32 bits to encode each address. This approach requires
treating the 32-bit value as signed, which limits the range of addresses that
could be encoded in other situations for other architectures, so it is
implemented as a config option that is selected only where necessary: very
clever.

Since this is real behavior that's used for real purposes, let's document it
here. I could only find oblique references in the document regarding config
entries without prompts:

- Describing the "visible" keyword: "It is similar to a conditional “prompt”
  attribute for individual menu entries."  This implies preexisting knowledge
  about prompts that was never explained.

- Describing the select keyword: "In general use select only for non-visible
  symbols (no prompts anywhere) and for symbols with no dependencies." This does
  spell out that symbols become invisible without prompts, but it's in an
  unrelated spot where a reader wouldn't expect to find it. It also isn't clear
  that "invisible" symbols can't even be altered by tweaking ".config".

- Describing the default keyword: "If an input prompt is visible the default
  value is presented to the user and can be overridden by him." This doesn't
  state anything about a missing prompt, though maybe it invites the reader to
  assume the inverse, if a prompt is not set, the value cannot be overridden.

Thanks,
Stephen

Stephen Brennan (1):
  Documentation: kbuild: explicitly document missing prompt

 Documentation/kbuild/kconfig-language.rst | 3 +++
 1 file changed, 3 insertions(+)

-- 
2.43.5

[PATCH 1/1] Documentation: kbuild: explicitly document missing prompt

[Stephen Brennan]

There are a few lines in the kbuild-language.rst document which
obliquely reference the behavior of config options without prompts.
But there is nothing in the obvious location that explicitly calls
out that users cannot edit config options unless they have a prompt.

Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com>
---
 Documentation/kbuild/kconfig-language.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
index 1fb3f5e6193c3..8e9306b599cd3 100644
--- a/Documentation/kbuild/kconfig-language.rst
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -54,40 +54,43 @@ applicable everywhere (see syntax).
 
 - type definition: "bool"/"tristate"/"string"/"hex"/"int"
 
   Every config option must have a type. There are only two basic types:
   tristate and string; the other types are based on these two. The type
   definition optionally accepts an input prompt, so these two examples
   are equivalent::
 
 	bool "Networking support"
 
   and::
 
 	bool
 	prompt "Networking support"
 
 - input prompt: "prompt" <prompt> ["if" <expr>]
 
   Every menu entry can have at most one prompt, which is used to display
   to the user. Optionally dependencies only for this prompt can be added
   with "if".
+  If a prompt is not set, then the config option cannot be changed by the user.
+  It will not appear in any menu, and even edits to ``.config`` cannot alter it.
+  It can still be set via "default" and "select" (see below).
 
 - default value: "default" <expr> ["if" <expr>]
 
   A config option can have any number of default values. If multiple
   default values are visible, only the first defined one is active.
   Default values are not limited to the menu entry where they are
   defined. This means the default can be defined somewhere else or be
   overridden by an earlier definition.
   The default value is only assigned to the config symbol if no other
   value was set by the user (via the input prompt above). If an input
   prompt is visible the default value is presented to the user and can
   be overridden by him.
   Optionally, dependencies only for this default value can be added with
   "if".
 
  The default value deliberately defaults to 'n' in order to avoid bloating the
  build. With few exceptions, new config options should not change this. The
  intent is for "make oldconfig" to add as little as possible to the config from
  release to release.
 
-- 
2.43.5

Re: [PATCH 1/1] Documentation: kbuild: explicitly document missing prompt

[Nathan Chancellor]

Hi Stephen,

On Tue, Aug 20, 2024 at 10:09:46AM -0700, Stephen Brennan wrote:
> There are a few lines in the kbuild-language.rst document which
> obliquely reference the behavior of config options without prompts.
> But there is nothing in the obvious location that explicitly calls
> out that users cannot edit config options unless they have a prompt.

Sure, I think the mention of "non-visible symbols" plus "no prompts
anywhere" in the select section is both a little cryptic to people who
are not pretty familiar with Kconfig and slightly disjoint from the
prompt section, so some clarification and expansion would not be a bad
idea! I do have some suggestions for the wording below.

> Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com>
> ---
>  Documentation/kbuild/kconfig-language.rst | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
> index 1fb3f5e6193c3..8e9306b599cd3 100644
> --- a/Documentation/kbuild/kconfig-language.rst
> +++ b/Documentation/kbuild/kconfig-language.rst
> @@ -54,40 +54,43 @@ applicable everywhere (see syntax).
>  
>  - type definition: "bool"/"tristate"/"string"/"hex"/"int"
>  
>    Every config option must have a type. There are only two basic types:
>    tristate and string; the other types are based on these two. The type
>    definition optionally accepts an input prompt, so these two examples
>    are equivalent::
>  
>  	bool "Networking support"
>  
>    and::
>  
>  	bool
>  	prompt "Networking support"
>  
>  - input prompt: "prompt" <prompt> ["if" <expr>]
>  
>    Every menu entry can have at most one prompt, which is used to display
>    to the user. Optionally dependencies only for this prompt can be added
>    with "if".
> +  If a prompt is not set, then the config option cannot be changed by the user.

Would "not present" be cleared than "not set"? It might also be worth
calling out here no prompt means a "non-visible" symbol since you
brought up the document brings that term up and does not really tell you
what it means.

Perhaps something like this might be just as clear while being
consistent with the terminology? Feel free to disagree though!

  If a prompt is not present, the config option is a non-visible symbol,
  meaning its value cannot be directly changed by the user (such as
  altering the value in ``.config``) and the option will not appear in
  any config menus. Its value can only be set via "default" and "select"
  (see below).

> +  It will not appear in any menu, and even edits to ``.config`` cannot alter it.
> +  It can still be set via "default" and "select" (see below).
>  
>  - default value: "default" <expr> ["if" <expr>]
>  
>    A config option can have any number of default values. If multiple
>    default values are visible, only the first defined one is active.
>    Default values are not limited to the menu entry where they are
>    defined. This means the default can be defined somewhere else or be
>    overridden by an earlier definition.
>    The default value is only assigned to the config symbol if no other
>    value was set by the user (via the input prompt above). If an input
>    prompt is visible the default value is presented to the user and can
>    be overridden by him.
>    Optionally, dependencies only for this default value can be added with
>    "if".
>  
>   The default value deliberately defaults to 'n' in order to avoid bloating the
>   build. With few exceptions, new config options should not change this. The
>   intent is for "make oldconfig" to add as little as possible to the config from
>   release to release.
>  
> -- 
> 2.43.5
> 

Re: [PATCH 1/1] Documentation: kbuild: explicitly document missing prompt

[Stephen Brennan]

Nathan Chancellor <nathan@kernel.org> writes:

> Hi Stephen,
>
> On Tue, Aug 20, 2024 at 10:09:46AM -0700, Stephen Brennan wrote:
>> There are a few lines in the kbuild-language.rst document which
>> obliquely reference the behavior of config options without prompts.
>> But there is nothing in the obvious location that explicitly calls
>> out that users cannot edit config options unless they have a prompt.
>
> Sure, I think the mention of "non-visible symbols" plus "no prompts
> anywhere" in the select section is both a little cryptic to people who
> are not pretty familiar with Kconfig and slightly disjoint from the
> prompt section, so some clarification and expansion would not be a bad
> idea! I do have some suggestions for the wording below.
>
>> Signed-off-by: Stephen Brennan <stephen.s.brennan@oracle.com>
>> ---
>>  Documentation/kbuild/kconfig-language.rst | 3 +++
>>  1 file changed, 3 insertions(+)
>> 
>> diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst
>> index 1fb3f5e6193c3..8e9306b599cd3 100644
>> --- a/Documentation/kbuild/kconfig-language.rst
>> +++ b/Documentation/kbuild/kconfig-language.rst
>> @@ -54,40 +54,43 @@ applicable everywhere (see syntax).
>>  
>>  - type definition: "bool"/"tristate"/"string"/"hex"/"int"
>>  
>>    Every config option must have a type. There are only two basic types:
>>    tristate and string; the other types are based on these two. The type
>>    definition optionally accepts an input prompt, so these two examples
>>    are equivalent::
>>  
>>  	bool "Networking support"
>>  
>>    and::
>>  
>>  	bool
>>  	prompt "Networking support"
>>  
>>  - input prompt: "prompt" <prompt> ["if" <expr>]
>>  
>>    Every menu entry can have at most one prompt, which is used to display
>>    to the user. Optionally dependencies only for this prompt can be added
>>    with "if".
>> +  If a prompt is not set, then the config option cannot be changed by the user.
>
> Would "not present" be cleared than "not set"? It might also be worth
> calling out here no prompt means a "non-visible" symbol since you
> brought up the document brings that term up and does not really tell you
> what it means.

I realized this exact issue re: "non-visible" upon re-reading the cover
letter & patch after sending, so I 100% agree.

> Perhaps something like this might be just as clear while being
> consistent with the terminology? Feel free to disagree though!
>
>   If a prompt is not present, the config option is a non-visible symbol,
>   meaning its value cannot be directly changed by the user (such as
>   altering the value in ``.config``) and the option will not appear in
>   any config menus. Its value can only be set via "default" and "select"
>   (see below).

I think this better than my suggestion :)

I'll send a v2 with that wording.

Thanks,
Stephen

>> +  It will not appear in any menu, and even edits to ``.config`` cannot alter it.
>> +  It can still be set via "default" and "select" (see below).
>>  
>>  - default value: "default" <expr> ["if" <expr>]
>>  
>>    A config option can have any number of default values. If multiple
>>    default values are visible, only the first defined one is active.
>>    Default values are not limited to the menu entry where they are
>>    defined. This means the default can be defined somewhere else or be
>>    overridden by an earlier definition.
>>    The default value is only assigned to the config symbol if no other
>>    value was set by the user (via the input prompt above). If an input
>>    prompt is visible the default value is presented to the user and can
>>    be overridden by him.
>>    Optionally, dependencies only for this default value can be added with
>>    "if".
>>  
>>   The default value deliberately defaults to 'n' in order to avoid bloating the
>>   build. With few exceptions, new config options should not change this. The
>>   intent is for "make oldconfig" to add as little as possible to the config from
>>   release to release.
>>  
>> -- 
>> 2.43.5
>>