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

Message

Stephen Brennan Aug. 20, 2024, 5:09 p.m. UTC

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(+)