* [PATCH 4/5] Documentation: generate docs for magic variables
2025-12-15 7:58 [PATCH 1/5] net: 9p: fix variable name in BAREBOX_MAGICVAR Ahmad Fatoum
2025-12-15 7:58 ` [PATCH 2/5] bootchooser: inline document global.bootchooser.reset_priorities Ahmad Fatoum
2025-12-15 7:58 ` [PATCH 3/5] reset_source: inline document global.system.reset* Ahmad Fatoum
@ 2025-12-15 7:59 ` Ahmad Fatoum
2025-12-15 7:59 ` [PATCH 5/5] Documentation: turn magic variables literals into references Ahmad Fatoum
2025-12-15 11:17 ` [PATCH 1/5] net: 9p: fix variable name in BAREBOX_MAGICVAR Sascha Hauer
4 siblings, 0 replies; 9+ messages in thread
From: Ahmad Fatoum @ 2025-12-15 7:59 UTC (permalink / raw)
To: barebox; +Cc: Ahmad Fatoum, Claude Sonnet 4.5
We have documentation for magic variables scattered around the docs, but
some variables docs is only available at runtime using the magicvar
command.
Let's include a listing of all extracted BAREBOX_MAGICVAR(..., ...)
occurrences in the code base formatted as a table in a hierarchical
manner.
The code is LLM-generated by feeding in the existing gen_commands.py
in addition to the prompt.
Co-developed-by: Claude Sonnet 4.5 <claude@anthropic.com>
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
Documentation/.gitignore | 1 +
Documentation/Makefile | 11 +-
Documentation/gen_magicvars.py | 357 +++++++++++++++++++++++++++++++
Documentation/user/variables.rst | 11 +-
4 files changed, 372 insertions(+), 8 deletions(-)
create mode 100755 Documentation/gen_magicvars.py
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index e8b2851d2552..4e35bebf8d51 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -2,4 +2,5 @@
build
commands
+magicvars.rst
html
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 825cd3ba0e7f..03daa0a2ab2f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -15,12 +15,17 @@ objtree ?= $(srctree)
docs: htmldocs FORCE
-htmldocs: FORCE
- @mkdir -p $(srctree)/Documentation/commands
- @$(srctree)/Documentation/gen_commands.py $(srctree) $(srctree)/Documentation/commands
+htmldocs: gen_commands gen_magicvars FORCE
@$(SPHINXBUILD) -b html -d $(objtree)/doctrees $(srctree)/Documentation \
$(objtree)/Documentation/html $(ALLSPHINXOPTS)
+gen_commands: FORCE
+ @mkdir -p $(srctree)/Documentation/commands
+ @$(srctree)/Documentation/gen_commands.py $(srctree) $(srctree)/Documentation/commands
+
+gen_magicvars: FORCE
+ @$(srctree)/Documentation/gen_magicvars.py $(srctree) $(srctree)/Documentation/user/magicvars.rst
+
dochelp: FORCE
@echo ' barebox internal documentation from ReST:'
@echo ' htmldocs - HTML'
diff --git a/Documentation/gen_magicvars.py b/Documentation/gen_magicvars.py
new file mode 100755
index 000000000000..e2bb02036051
--- /dev/null
+++ b/Documentation/gen_magicvars.py
@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0-only
+
+import os
+import re
+import sys
+import hashlib
+from collections import defaultdict
+
+MAGICVAR = re.compile(r'BAREBOX_MAGICVAR\s*\(\s*(\S+)\s*,\s*"(.*?)"\s*\)')
+MAGICVAR_START = re.compile(r'BAREBOX_MAGICVAR\s*\(\s*(\S+)\s*,\s*"(.*?)$')
+MAGICVAR_CONT = re.compile(r'(.*?)"\s*\)')
+
+UNESCAPE = re.compile(r'''\\(["\\])''')
+
+# Global override dictionary to map directories to specific arch or board
+DIRECTORY_OVERRIDES = {
+ 'drivers/soc/kvx': {'arch': 'kvx'},
+}
+
+
+def string_unescape(s):
+ return re.sub(UNESCAPE, r'\1', s.replace(r'\t', '').replace(r'\n', ''))
+
+
+def parse_c(filepath):
+ """Parse a C file and extract BAREBOX_MAGICVAR declarations."""
+ magicvars = []
+
+ with open(filepath, 'r') as f:
+ content = f.read()
+
+ # Try to find all BAREBOX_MAGICVAR occurrences
+ # First, try single-line matches
+ for match in MAGICVAR.finditer(content):
+ varname = match.group(1).strip()
+ description = string_unescape(match.group(2))
+ magicvars.append((varname, description))
+
+ # For multi-line matches, we need to search line by line
+ lines = content.split('\n')
+ i = 0
+ while i < len(lines):
+ line = lines[i]
+
+ # Check if this line was already matched by single-line regex
+ if MAGICVAR.search(line):
+ i += 1
+ continue
+
+ # Try multi-line match
+ m = MAGICVAR_START.search(line)
+ if m:
+ varname = m.group(1).strip()
+ description = m.group(2)
+ i += 1
+
+ # Continue reading lines until we find the closing
+ while i < len(lines):
+ line = lines[i]
+ m_end = MAGICVAR_CONT.search(line)
+ if m_end:
+ description += m_end.group(1)
+ break
+ else:
+ description += line
+ i += 1
+
+ description = string_unescape(description)
+ magicvars.append((varname, description))
+
+ i += 1
+
+ return magicvars
+
+
+def categorize_file(filepath):
+ """Determine if a file is arch-specific, board-specific, or common."""
+ parts = filepath.split(os.sep)
+
+ arch = None
+ board = None
+
+ # Check for directory overrides first
+ for override_path, override_spec in DIRECTORY_OVERRIDES.items():
+ override_parts = override_path.split('/')
+ # Check if the filepath starts with the override path
+ if len(parts) >= len(override_parts):
+ if all(parts[i] == override_parts[i] for i in range(len(override_parts))):
+ # This file matches the override path
+ if 'arch' in override_spec:
+ arch = override_spec['arch']
+ if 'board' in override_spec:
+ board = override_spec['board']
+ return arch, board
+
+ # Check for arch
+ if 'arch' in parts:
+ arch_idx = parts.index('arch')
+ if arch_idx + 1 < len(parts):
+ arch = parts[arch_idx + 1]
+
+ # Check for board
+ if 'boards' in parts:
+ boards_idx = parts.index('boards')
+ if boards_idx + 1 < len(parts):
+ board = parts[boards_idx + 1]
+
+ return arch, board
+
+
+def get_prefix_group(varname):
+ """Get the prefix group for a variable name."""
+ if '.' not in varname:
+ return None # No prefix group
+
+ parts = varname.split('.')
+ if len(parts) == 2:
+ return parts[0] # e.g., "global" from "global.option"
+ else:
+ return '.'.join(parts[:-1]) # e.g., "global.bootm" from "global.bootm.option"
+
+
+def hoist_single_elements(grouped_vars):
+ """Hoist single-element groups to their parent group."""
+ # Find single-element groups
+ single_element_groups = []
+ for prefix, vars_list in list(grouped_vars.items()):
+ if prefix and len(vars_list) == 1:
+ single_element_groups.append(prefix)
+
+ # Hoist them
+ for prefix in single_element_groups:
+ varname, description = grouped_vars[prefix][0]
+ del grouped_vars[prefix]
+
+ # Find parent prefix
+ if '.' in prefix:
+ parent_prefix = '.'.join(prefix.split('.')[:-1])
+ else:
+ parent_prefix = None
+
+ grouped_vars[parent_prefix].append((varname, description))
+
+ return grouped_vars
+
+
+def generate_table(vars_list, arch=None, board=None):
+ """Generate a ReST table for a list of variables."""
+ if not vars_list:
+ return ""
+
+ # Sort alphabetically
+ vars_list = sorted(vars_list, key=lambda x: x[0])
+
+ lines = []
+ lines.append(".. list-table::")
+ lines.append(" :header-rows: 1")
+ lines.append(" :align: left")
+ lines.append(" :widths: 30 70")
+ lines.append(" :width: 100%")
+ lines.append("")
+ lines.append(" * - Variable")
+ lines.append(" - Description")
+
+ for varname, description in vars_list:
+ # Generate anchor
+ anchor = varname.replace('.', '_')
+ if board:
+ anchor = f"{anchor}_{board}"
+ elif arch:
+ anchor = f"{anchor}_{arch}"
+
+ lines.append(f" * - .. _magicvar_{anchor}:")
+ lines.append("")
+ lines.append(f" ``{varname}``")
+ lines.append(f" - {description}")
+
+ return '\n'.join(lines)
+
+
+def generate_rst(common_vars, arch_vars, board_vars):
+ """Generate the complete ReST documentation."""
+ out = []
+
+ # Group common variables by prefix
+ grouped = defaultdict(list)
+ for varname, description in common_vars:
+ prefix = get_prefix_group(varname)
+ grouped[prefix].append((varname, description))
+
+ # Hoist single-element groups
+ grouped = hoist_single_elements(grouped)
+
+ # Build a hierarchy tree
+ hierarchy = defaultdict(lambda: {'vars': [], 'children': {}})
+
+ for prefix, vars_list in grouped.items():
+ if prefix is None:
+ hierarchy[None]['vars'] = vars_list
+ else:
+ # Split into top-level and sub-level
+ parts = prefix.split('.')
+ if len(parts) == 1:
+ # Top-level like "global"
+ hierarchy[prefix]['vars'] = vars_list
+ else:
+ # Sub-level like "global.bootm"
+ top_level = parts[0]
+ hierarchy[top_level]['children'][prefix] = vars_list
+
+ # Generate output with hierarchy
+ # First, handle "No prefix" group
+ if None in hierarchy and hierarchy[None]['vars']:
+ out.append("No prefix")
+ out.append("-" * len(out[-1]))
+ out.append("")
+ out.append(generate_table(hierarchy[None]['vars']))
+ out.append("")
+
+ # Then handle top-level groups in alphabetical order
+ sorted_top_level = sorted([k for k in hierarchy.keys() if k is not None])
+
+ for top_prefix in sorted_top_level:
+ group = hierarchy[top_prefix]
+
+ # Top-level heading
+ out.append(f"{top_prefix}.*")
+ out.append("-" * len(out[-1]))
+ out.append("")
+
+ # Top-level variables table (if any)
+ if group['vars']:
+ out.append(generate_table(group['vars']))
+ out.append("")
+
+ # Sub-level groups
+ for sub_prefix in sorted(group['children'].keys()):
+ out.append(f"{sub_prefix}.*")
+ out.append("^" * len(out[-1]))
+ out.append("")
+ out.append(generate_table(group['children'][sub_prefix]))
+ out.append("")
+
+ # Architecture-specific variables
+ if arch_vars:
+ for arch in sorted(arch_vars.keys()):
+ out.append(f"{arch}-specific variables")
+ out.append("-" * len(out[-1]))
+ out.append("")
+ out.append(generate_table(arch_vars[arch], arch=arch))
+ out.append("")
+
+ # Board-specific variables
+ if board_vars:
+ out.append("Board-specific variables")
+ out.append("-" * len(out[-1]))
+ out.append("")
+
+ for board in sorted(board_vars.keys()):
+ out.append(board)
+ out.append("^" * len(out[-1]))
+ out.append("")
+ out.append(generate_table(board_vars[board], board=board))
+ out.append("")
+
+ return '\n'.join(out)
+
+
+def main():
+ if len(sys.argv) != 3:
+ print("Usage: gen_magicvars.py <source_dir> <output_file>", file=sys.stderr)
+ sys.exit(1)
+
+ source_dir = sys.argv[1]
+ output_file = sys.argv[2]
+
+ # Collect all magic variables
+ all_vars = defaultdict(lambda: defaultdict(set)) # {varname: {description: set of (arch, board)}}
+
+ for root, dirs, files in os.walk(source_dir):
+ for name in files:
+ if name.endswith('.c'):
+ filepath = os.path.join(root, name)
+ relpath = os.path.relpath(filepath, source_dir)
+
+ arch, board = categorize_file(relpath)
+ magicvars = parse_c(filepath)
+
+ for varname, description in magicvars:
+ all_vars[varname][description].add((arch, board))
+
+ # Check for inconsistent descriptions
+ for varname, descriptions in all_vars.items():
+ if len(descriptions) > 1:
+ print(f"gen_magicvars: warning: variable '{varname}' has multiple different descriptions", file=sys.stderr)
+ for desc in descriptions:
+ print(f" - {desc}", file=sys.stderr)
+
+ # Organize variables into categories
+ common_vars = []
+ arch_vars = defaultdict(list)
+ board_vars = defaultdict(list)
+
+ for varname, descriptions in all_vars.items():
+ # Use the first description (or we could merge them)
+ description = list(descriptions.keys())[0]
+ locations = list(descriptions.values())[0]
+
+ # Determine where this variable should go
+ is_board = any(board is not None for arch, board in locations)
+ is_arch = any(arch is not None and board is None for arch, board in locations)
+ is_common = any(arch is None and board is None for arch, board in locations)
+
+ # Priority: board > arch > common
+ if is_board:
+ for arch, board in locations:
+ if board is not None:
+ board_vars[board].append((varname, description))
+ elif is_arch:
+ for arch, board in locations:
+ if arch is not None and board is None:
+ arch_vars[arch].append((varname, description))
+ elif is_common:
+ common_vars.append((varname, description))
+
+ # Remove duplicates within each category
+ common_vars = list(set(common_vars))
+ for arch in arch_vars:
+ arch_vars[arch] = list(set(arch_vars[arch]))
+ for board in board_vars:
+ board_vars[board] = list(set(board_vars[board]))
+
+ # Generate ReST documentation
+ rst = generate_rst(common_vars, arch_vars, board_vars)
+
+ # Write to output file
+
+ # Only write the new rst if it differs from the old one.
+ hash_old = hashlib.sha1()
+ try:
+ f = open(output_file, 'rb')
+ hash_old.update(f.read())
+ except Exception:
+ pass
+
+ hash_new = hashlib.sha1()
+ hash_new.update(rst.encode('utf-8'))
+ if hash_old.hexdigest() == hash_new.hexdigest():
+ return
+
+ with open(output_file, 'w') as f:
+ f.write(rst)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/Documentation/user/variables.rst b/Documentation/user/variables.rst
index cb1296c06d02..61808f1d72de 100644
--- a/Documentation/user/variables.rst
+++ b/Documentation/user/variables.rst
@@ -94,13 +94,13 @@ This example changes the partitioning of the nand0 device:
.. _magicvars:
Magic variables
----------------
+===============
Some variables have special meanings and influence the behaviour
of barebox. Most but not all of them are consolidated in the :ref:`global_device`.
Since it's hard to remember which variables these are and if the current
barebox has support for them the :ref:`command_magicvar` command can print a list
-of all variables with special meaning along with a short description:
+of all active variables with special meaning along with a short description:
.. code-block:: console
@@ -108,9 +108,6 @@ of all variables with special meaning along with a short description:
OPTARG optarg for hush builtin getopt
PATH colon separated list of paths to search for executables
PS1 hush prompt
- armlinux_architecture ARM machine ID
- armlinux_system_rev ARM system revision
- armlinux_system_serial ARM system serial
automount_path mountpath passed to automount scripts
bootargs Linux Kernel parameters
bootsource The source barebox has been booted from
@@ -118,3 +115,7 @@ of all variables with special meaning along with a short description:
global.boot.default default boot order
...
+Above output will only list magic variables that were compiled.
+Below is a full listing of all currently documented magic variables:
+
+.. include:: magicvars.rst
--
2.47.3
^ permalink raw reply [flat|nested] 9+ messages in thread* [PATCH 5/5] Documentation: turn magic variables literals into references
2025-12-15 7:58 [PATCH 1/5] net: 9p: fix variable name in BAREBOX_MAGICVAR Ahmad Fatoum
` (2 preceding siblings ...)
2025-12-15 7:59 ` [PATCH 4/5] Documentation: generate docs for magic variables Ahmad Fatoum
@ 2025-12-15 7:59 ` Ahmad Fatoum
2025-12-15 11:17 ` [PATCH 1/5] net: 9p: fix variable name in BAREBOX_MAGICVAR Sascha Hauer
4 siblings, 0 replies; 9+ messages in thread
From: Ahmad Fatoum @ 2025-12-15 7:59 UTC (permalink / raw)
To: barebox; +Cc: Ahmad Fatoum
With the script added in the previous commit changed to emit the name of
all magic variables, this commit proceeds to search-and-replace
occurrences of ``$magic.var`` and ``magic.var`` with a reference link.
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
Documentation/devel/troubleshooting.rst | 3 +-
.../migration-guides/migration-2025.02.0.rst | 3 +-
.../migration-guides/migration-2025.04.0.rst | 3 +-
.../migration-guides/migration-2025.05.0.rst | 3 +-
Documentation/user/bootchooser.rst | 31 ++++++++++++-------
Documentation/user/booting-linux.rst | 30 ++++++++++--------
Documentation/user/devicetree.rst | 15 +++++----
Documentation/user/networking.rst | 11 ++++---
Documentation/user/reboot-mode.rst | 25 +++++++++------
Documentation/user/reset-reason.rst | 5 ++-
Documentation/user/security.rst | 4 +--
Documentation/user/usb.rst | 14 ++++-----
Documentation/user/versioning.rst | 5 +--
13 files changed, 89 insertions(+), 63 deletions(-)
diff --git a/Documentation/devel/troubleshooting.rst b/Documentation/devel/troubleshooting.rst
index 8e31148b9c06..f7896a2eb377 100644
--- a/Documentation/devel/troubleshooting.rst
+++ b/Documentation/devel/troubleshooting.rst
@@ -379,7 +379,8 @@ to :ref:`visualize only the fixups that were applied by barebox to the device tr
If you are sure that the kernel is indeed being loaded, the ``earlycon`` kernel
feature can enable early debugging output before kernel serial drivers are loaded.
-barebox can fixup an earlycon option if ``global.bootm.earlycon=1`` is specified.
+barebox can fixup an earlycon option if
+:ref:`global.bootm.earlycon=1 <magicvar_global_bootm_earlycon>` is specified.
Spurious Aborts/Hangs
=====================
diff --git a/Documentation/migration-guides/migration-2025.02.0.rst b/Documentation/migration-guides/migration-2025.02.0.rst
index c585d2e96341..9210edf1d4b1 100644
--- a/Documentation/migration-guides/migration-2025.02.0.rst
+++ b/Documentation/migration-guides/migration-2025.02.0.rst
@@ -4,7 +4,8 @@ Release v2025.02.0
Environment Auto-Probe
----------------------
-A new magic variable ``global.env.autoprobe`` now controls whether barebox
+A new magic variable :ref:`global.env.autoprobe <magicvar_global_env_autoprobe>`
+now controls whether barebox
will automatically probe known block devices for a GPT barebox environment
partition if no environment was specified by other means.
diff --git a/Documentation/migration-guides/migration-2025.04.0.rst b/Documentation/migration-guides/migration-2025.04.0.rst
index de7efdf47fe6..b6d077c85717 100644
--- a/Documentation/migration-guides/migration-2025.04.0.rst
+++ b/Documentation/migration-guides/migration-2025.04.0.rst
@@ -4,7 +4,8 @@ Release v2025.04.0
Boot overrides
--------------
-It's no longer possible to override ``global.bootm.image`` with
+It's no longer possible to override
+:ref:`global.bootm.image <magicvar_global_bootm_image>` with
the new ``boot -o`` syntax. This override led to issues when
substituting wildly different boot image formats.
diff --git a/Documentation/migration-guides/migration-2025.05.0.rst b/Documentation/migration-guides/migration-2025.05.0.rst
index f22c9f7c02c5..1cab96e2bd09 100644
--- a/Documentation/migration-guides/migration-2025.05.0.rst
+++ b/Documentation/migration-guides/migration-2025.05.0.rst
@@ -74,7 +74,8 @@ Shell and magic variables
* ``/dev/fw_cfg0`` has been renamed to ``/dev/fw_cfg``
-* ``global.boot.default`` is now ``bootsource net`` by default.
+* :ref:`global.boot.default <magicvar_global_boot_default>` is now
+ ``bootsource net`` by default.
This does not affect users setting ``nv boot.default``, but for
others, barebox will look for bootloader spec on the bootsource
diff --git a/Documentation/user/bootchooser.rst b/Documentation/user/bootchooser.rst
index 9cf8d4c81737..360305e92e3f 100644
--- a/Documentation/user/bootchooser.rst
+++ b/Documentation/user/bootchooser.rst
@@ -32,7 +32,9 @@ Bootchooser Targets
-------------------
A *bootchooser* boot target represents one target that barebox can boot. The
-known targets are set in ``global.bootchooser.targets``. A target consists of a
+known targets are set in
+:ref:`global.bootchooser.targets <magicvar_global_bootchooser_targets>`.
+A target consists of a
set of variables in the ``global.bootchooser.<targetname>`` namespace. The
following configuration variables describe a *bootchooser* boot target:
@@ -46,7 +48,9 @@ following configuration variables describe a *bootchooser* boot target:
Defaults to ``bootchooser.default_attempts``, see below.
``global.bootchooser.<targetname>.default_priority``
The default priority of a boot target.
- Defaults to ``global.bootchooser.default_priority``, see below.
+ Defaults to
+ :ref:`global.bootchooser.default_priority <magicvar_global_bootchooser_default_priority>`,
+ see below.
The *bootchooser* algorithm generally only starts boot targets that have a ``priority``
> 0 and a ``remaining_attempts`` counter > 0.
@@ -76,7 +80,9 @@ no remaining attempts left.
To prevent ending up in an unbootable system after a number of failed boot
attempts, there is also a built-in mechanism to reset the counters to their defaults,
-controlled by the ``global.bootchooser.reset_attempts`` variable.
+controlled by the
+:ref:`global.bootchooser.reset_attempts <magicvar_global_bootchooser_reset_attempts>`
+variable.
.. _bootchooser,attempts_lock:
@@ -98,7 +104,8 @@ interpreted as ``0``, meaning that attempts are decremented normally.
The ``attempts_locked`` value does not influence the decision on which target
to boot if any, only whether to decrement the attempts when booting.
-If ``global.bootchooser.retry`` is enabled (set to ``1``), the bootchooser
+If :ref:`global.bootchooser.retry <magicvar_global_bootchooser_retry>`
+is enabled (set to ``1``), the bootchooser
algorithm will iterate through all valid boot targets (and decrease their
counters) until one succeeds or none is left.
If it is disabled only one attempt will be made for each bootchooser call.
@@ -149,17 +156,17 @@ General Bootchooser Options
In addition to the boot target options described above, *bootchooser* has some general
options not specific to any boot target.
-``global.bootchooser.disable_on_zero_attempts``
+:ref:`global.bootchooser.disable_on_zero_attempts <magicvar_global_bootchooser_disable_on_zero_attempts>`
Boolean flag. If set to 1, *bootchooser* disables a boot target (sets priority
to 0) whenever the remaining attempts counter reaches 0. Defaults to 0.
-``global.bootchooser.default_attempts``
+:ref:`global.bootchooser.default_attempts <magicvar_global_bootchooser_default_attempts>`
The default number of attempts that a boot target shall be tried before skipping
it, used when not overwritten with the boot target specific variable of the same
name. Defaults to 3.
-``global.bootchooser.default_priority``
+:ref:`global.bootchooser.default_priority <magicvar_global_bootchooser_default_priority>`
The default priority of a boot target when not overwritten with the target
specific variable of the same name. Defaults to 1.
-``global.bootchooser.reset_attempts``
+:ref:`global.bootchooser.reset_attempts <magicvar_global_bootchooser_reset_attempts>`
A space-separated list of conditions (checked during bootchooser start) that
shall cause the ``remaining_attempts`` counters of all enabled targets to be
reset. Possible values:
@@ -170,22 +177,22 @@ options not specific to any boot target.
* ``reset``: If a generic reset (``$global.system.reset="RST"``) is detected.
* ``all-zero``: If the ``remaining_attempts`` counters of all enabled targets
are zero.
-``global.bootchooser.reset_priorities``
+:ref:`global.bootchooser.reset_priorities <magicvar_global_bootchooser_reset_priorities>`
A space-separated list of conditions (checked during bootchooser start) that
shall cause the ``priority`` of all boot targets to be reset. Possible values:
* empty: Priorities will never be reset (default).
* ``all-zero``: If all boot targets have zero ``priority``.
-``global.bootchooser.retry``
+:ref:`global.bootchooser.retry <magicvar_global_bootchooser_retry>`
If set to 1, *bootchooser* retries booting until one succeeds or no more valid
boot targets exist.
Otherwise the ``boot`` command will return with an error after the first failed
boot target. Defaults to 0.
-``global.bootchooser.state_prefix``
+:ref:`global.bootchooser.state_prefix <magicvar_global_bootchooser_state_prefix>`
If set, this makes *bootchooser* use the *state* framework as backend for
storing run-time data and defines the name of the state instance to use, see
:ref:`below <bootchooser,state_framework>`. Defaults to an empty string.
-``global.bootchooser.targets``
+:ref:`global.bootchooser.targets <magicvar_global_bootchooser_targets>`
Space-separated list of boot targets that are used. For each entry in the list
a corresponding set of variables must exist in the chosen *bootchooser* storage
backend.
diff --git a/Documentation/user/booting-linux.rst b/Documentation/user/booting-linux.rst
index 6a41de6712ea..ed1ec3f68a93 100644
--- a/Documentation/user/booting-linux.rst
+++ b/Documentation/user/booting-linux.rst
@@ -25,7 +25,7 @@ following images are supported:
* FIT images, containing a zImage or Image
The images can either be passed directly to the bootm command as argument or
-in the ``global.bootm.image`` variable:
+in the :ref:`global.bootm.image <magicvar_global_bootm_image>` variable:
.. code-block:: sh
@@ -37,8 +37,8 @@ in the ``global.bootm.image`` variable:
bootm
When barebox has an internal devicetree it is passed to the kernel. You can
-specify an alternative devicetree with the ``-o DTS`` option or the ``global.bootm.oftree``
-variable:
+specify an alternative devicetree with the ``-o DTS`` option or the
+:ref:`global.bootm.oftree <magicvar_global_bootm_oftree>` variable:
.. code-block:: sh
@@ -50,8 +50,8 @@ variable:
global.bootm.image=/path/to/zImage
bootm
-To use an initramfs, use the ``-r`` option or the ``global.bootm.initrd``
-variable:
+To use an initramfs, use the ``-r`` option or the
+:ref:`global.bootm.initrd <magicvar_global_bootm_initrd>` variable:
.. code-block:: sh
@@ -73,14 +73,15 @@ It's also possible to select a specific configuration explicitly:
**NOTE:** it may happen that barebox is probed from the devicetree, but you have
want to start a Kernel without passing a devicetree. In this case set the
-``global.bootm.boot_atag`` variable to ``true``.
+:ref:`global.bootm.boot_atag <magicvar_global_bootm_boot_atag_arm>` variable to
+``true``.
Passing Kernel Arguments
^^^^^^^^^^^^^^^^^^^^^^^^
The simple method to pass bootargs to the kernel is with
``CONFIG_FLEXIBLE_BOOTARGS`` disabled: in this case the bootm command
-takes the bootargs from the ``bootargs`` environment variable.
+takes the bootargs from the :ref:`bootargs <magicvar_bootargs>` environment variable.
With ``CONFIG_FLEXIBLE_BOOTARGS`` enabled, the bootargs are composed
from different :ref:`global device<global_device>` variables. All variables beginning
@@ -128,7 +129,8 @@ Creating root= options for the Kernel
It's a common case that the Linux Kernel is loaded from a filesystem
that later becomes the root filesystem for the Kernel. For several
filesystems barebox can automatically append a suitable root= option
-to the Kernel command line. This is done when ``global.bootm.appendroot``
+to the Kernel command line. This is done when
+:ref:`global.bootm.appendroot <magicvar_global_bootm_appendroot>`
is true. How the root= option is appended depends on the device type
and filesystem the kernel is booted from. For disk like devices (SD/MMC,
ATA) the partition UUID will be used, the root= option will be something
@@ -171,8 +173,8 @@ This is done so that following boot entries do not leak command line
parameters from the previous boot entries.
This entry can be booted with ``boot mmc``. It can also be made the default by
-setting the ``global.boot.default`` variable to ``mmc`` and then calling
-``boot`` without arguments.
+setting the :ref:`global.boot.default <magicvar_global_boot_default>` variable
+to ``mmc`` and then calling ``boot`` without arguments.
Especially for development, it can be useful to override only parts of
the images used in a boot. To do so, set ``CONFIG_BOOT_OVERRIDE=y``
@@ -191,7 +193,7 @@ bootloader spec file detected at runtime as described in the next section.
There is also a number of generic default boot targets available, when
``CONFIG_BOOT_DEFAULTS`` is enabled. These expands to a single device at most:
-* ``bootsource``: expands to the device barebox booted from
+* :ref:`bootsource <magicvar_bootsource>`: expands to the device barebox booted from
* ``diskuuid.*``: expands to the device with specified ``*`` diskuuid
For these targets that expand to a single device, a partition can also be specified,
@@ -268,7 +270,8 @@ The entry can be listed with the ``-l`` option:
linux: 11ab7c89d02c4f66a4e2474ea25b2b84.15/linux
When the SD card shows up as ``mmc1`` in barebox, this entry can be booted with
-``boot mmc1`` or by setting ``global.boot.default`` to ``mmc1``.
+``boot mmc1`` or by setting
+:ref:`global.boot.default <magicvar_global_boot_default>` to ``mmc1``.
A bootloader spec entry can also reside on an NFS server by pointing the boot
command at the mount point
@@ -318,7 +321,8 @@ Note that barebox will pass the same IP settings to the kernel, i.e. it passes
and ``ip=dhcp`` for a dynamic DHCP setup. ``<linuxdevname>`` is a configurable value.
set ``nv.dev.<ethdev>.linuxdevname`` to the name the device has in Linux.
-By default, barebox uses the variables ``global.user`` and ``global.hostname``
+By default, barebox uses the variables ``global.user`` and
+:ref:`global.hostname <magicvar_global_hostname>`
to retrieve its kernel image over TFTP, which makes it possible to use multiple
boards for multiple users with one single server.
You can adjust those variables using nvvars with these commands::
diff --git a/Documentation/user/devicetree.rst b/Documentation/user/devicetree.rst
index 9702db5c5ad2..82436f0dbcbb 100644
--- a/Documentation/user/devicetree.rst
+++ b/Documentation/user/devicetree.rst
@@ -108,27 +108,30 @@ Device tree overlays on the kernel device tree
Overlays can be applied to the kernel device tree before it is handed over to
the kernel. The behaviour is controlled by different variables:
-``global.of.overlay.path``
+:ref:`global.of.overlay.path <magicvar_global_of_overlay_path>`
Overlays are read from this path. The path can either be a directory which
contains the overlays or a path to a FIT-image. barebox will try to apply all
overlays found if not limited by one of the other variables below. When the
path given here is an absolute path it is used as is. A relative path is
relative to ``/`` or relative to the rootfs when using bootloader spec.
-``global.of.overlay.compatible``
+:ref:`global.of.overlay.compatible <magicvar_global_of_overlay_compatible>`
This is a space separated list of compatibles. Only overlays matching one of
these compatibles will be applied. When this list is empty then all overlays
will be applied. Overlays that don't have a compatible are considered being
always compatible.
-``global.of.overlay.pattern``
+:ref:`global.of.overlay.pattern <magicvar_global_of_overlay_pattern>`
This is a space separated list of file patterns or FIT-image config-node name
patterns. An overlay is only applied when its filename or FIT-image
config-node name matches one of the patterns. The patterns can contain ``*``
and ``?`` as wildcards. The default is ``*`` which means all files or FIT-Image
config-nodes are applied.
-``global.of.overlay.filter``
+:ref:`global.of.overlay.filter <magicvar_global_of_overlay_filter>`
This is a space separated list of filters to apply. There are two generic filters:
- ``pattern`` matches ``global.of.overlay.pattern`` above, ``compatible`` matches
- ``global.of.overlay.compatible`` above. The default is ``pattern compatible``
+ ``pattern`` matches
+ :ref:`global.of.overlay.pattern <magicvar_global_of_overlay_pattern>` above,
+ ``compatible`` matches
+ :ref:`global.of.overlay.compatible <magicvar_global_of_overlay_compatible>` above.
+ The default is ``pattern compatible``
which means the two generic filters are active. This list may be replaced or
supplemented by board specific filters.
diff --git a/Documentation/user/networking.rst b/Documentation/user/networking.rst
index 605936c6a895..d1db2768ad20 100644
--- a/Documentation/user/networking.rst
+++ b/Documentation/user/networking.rst
@@ -160,14 +160,17 @@ both TFTP and NFS. On first access, an Ethernet interface will be brought
up and file operations will be forwarded to a host specified by global
variables:
-- ``/mnt/tftp``: will use ``$global.net.server`` as TFTP server
+- ``/mnt/tftp``: will use :ref:`global.net.server <magicvar_global_net_server>`
+ as TFTP server
-- ``/mnt/nfs``: will use ``$global.net.server`` as NFS server
+- ``/mnt/nfs``: will use :ref:`global.net.server <magicvar_global_net_server>`
+ as NFS server
and ``/home/${global.user}/nfsroot/${global.hostname}`` as nfsroot.
By default, a RPC lookup will be conducted to determine mount and
NFS ports, but these can be overridden together using a user-specified
- by means of ``global.nfs.port``. The latter is equivalent to specifying
- ``-o port=$global.nfs.port,mountport=$global.nfs.port`` as argument
+ by means of :ref:`global.nfs.port <magicvar_global_nfs_port>`.
+ The latter is equivalent to specifying
+ ``-o port=${global.nfs.port},mountport=${global.nfs.port}`` as argument
to the :ref:`mount command <command_mount>`.
Network console
diff --git a/Documentation/user/reboot-mode.rst b/Documentation/user/reboot-mode.rst
index 1929a67e0bc9..2e761c65f6a3 100644
--- a/Documentation/user/reboot-mode.rst
+++ b/Documentation/user/reboot-mode.rst
@@ -44,8 +44,10 @@ the device. By convention, this should end with ``.reboot_mode``, e.g.::
};
Reboot mode providers have priorities. The provider with the highest
-priority has its parameters aliased as ``$global.system.reboot_mode.prev``
-and ``$global.system.reboot_mode.next``. After executing the init scripts,
+priority has its parameters aliased as
+:ref:`global.system.reboot_mode.prev <magicvar_global_system_reboot_mode_prev>`
+and :ref:`global.system.reboot_mode.next <magicvar_global_system_reboot_mode_next>`.
+After executing the init scripts,
barebox startup will ``source /env/bmode/${global.system.reboot_mode.prev}``
if available. Example usage::
@@ -74,7 +76,8 @@ functionality. They all ultimately serve different purposes, however.
Comparison to reset reason
---------------------------
-The reset reason ``$global.system.reset`` is populated by different drivers
+The reset reason :ref:`global.system.reset <magicvar_global_system_reset>` is
+populated by different drivers
to reflect the hardware cause of a reset, e.g. a watchdog. A reboot mode
describes the OS intention behind a reset, e.g. to fall into a recovery
mode. Reboot modes besides the default ``normal`` mode usually accompany
@@ -84,15 +87,17 @@ to activate the next reboot mode).
Comparison to bootsource
------------------------
-``$bootsource`` reflects the current boot's medium as indicated by the
-SoC. In cases where the reboot mode is used to communicate with the BootROM,
-``$bootsource`` and ``$bootsource_instance`` may describe the same device
-as the reboot mode.
+:ref:`bootsource <magicvar_bootsource>` reflects the current boot's medium as
+indicated by the SoC.
+In cases where the reboot mode is used to communicate with the BootROM,
+:ref:`bootsource <magicvar_bootsource>` and
+:ref:`bootsource_instance <magicvar_bootsource_instance>` may describe the same
+device as the reboot mode.
For cases, where the communication instead happens between barebox and an OS,
-they can be completely different, e.g. ``$bootsource`` may say barebox was
-booted from ``spi-nor``, while the reboot mode describes that barebox should
-boot the Kernel off a USB flash drive.
+they can be completely different, e.g. :ref:`bootsource <magicvar_bootsource>`
+may say barebox was booted from ``spi-nor``, while the reboot mode describes
+that barebox should boot the Kernel off a USB flash drive.
Comparison to barebox state
---------------------------
diff --git a/Documentation/user/reset-reason.rst b/Documentation/user/reset-reason.rst
index e46f2ca684ab..4c40313a80ca 100644
--- a/Documentation/user/reset-reason.rst
+++ b/Documentation/user/reset-reason.rst
@@ -14,9 +14,8 @@ For example it should wait for another update (for the case the cause of a
crash is a failed update) or should start into a fall back system instead.
In order to handle failing systems gracefully the bootloader needs the
-information why it runs. This is called the "reset reason". It is provided by
-the global variable ``system.reset`` and can be used in scripts via
-``$global.system.reset``.
+information why it runs. This is called the "reset reason". It is available
+to scripts as :ref:`global.system.reset <magicvar_global_system_reset>`.
The following values can help to detect the reason why the bootloader runs:
diff --git a/Documentation/user/security.rst b/Documentation/user/security.rst
index 5a23bd83ba65..94184ab8e893 100644
--- a/Documentation/user/security.rst
+++ b/Documentation/user/security.rst
@@ -99,8 +99,8 @@ different compression algorithm.
The fail-safe alternative is to use a parameter name understood only by the
initramfs (e.g. ``verity_root=``) in all bootloader scripts. If the
``root=$dev`` is fixed up by barebox dynamically, the
-``$global.bootm.root_param`` variable can be used to customize the name of the
-parameter passed to Linux.
+:ref:`global.bootm.root_param <magicvar_global_bootm_root_param>` variable can
+be used to customize the name of the parameter passed to Linux.
Disabling the shell
^^^^^^^^^^^^^^^^^^^
diff --git a/Documentation/user/usb.rst b/Documentation/user/usb.rst
index f233927656bc..c6ff383c565d 100644
--- a/Documentation/user/usb.rst
+++ b/Documentation/user/usb.rst
@@ -27,7 +27,7 @@ following to ``/env/network/eth0-discover``:
usb
Alternatively, a ``detect -a`` (all) can be forced in ``ifup`` by setting
-``global.net.ifup_force_detect=1``.
+:ref:`global.net.ifup_force_detect=1 <magicvar_global_net_ifup_force_detect>`.
USB mass storage
^^^^^^^^^^^^^^^^
@@ -314,24 +314,24 @@ CONFIG_USB_GADGET_AUTOSTART enabled.
USB Gadget autostart Options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``global.usbgadget.autostart``
+:ref:`global.usbgadget.autostart <magicvar_global_usbgadget_autostart>`
Boolean flag. If set to 1, usbgadget will be started automatically on boot and
enable USB OTG mode. (Default 0).
-``global.usbgadget.acm``
+:ref:`global.usbgadget.acm <magicvar_global_usbgadget_acm>`
Boolean flag. If set to 1, CDC ACM function will be created.
See :ref:`command_usbgadget` -a. (Default 0).
-``global.system.partitions``
+:ref:`global.system.partitions <magicvar_global_system_partitions>`
Common function description for all of DFU, fastboot and USB mass storage
gadgets.
See :ref:`usbgadget_partitions` above for the syntax.
Both Fastboot and DFU partitions also have dedicated override
variables for backwards-compatibility:
-``global.usbgadget.dfu_function``
+:ref:`global.usbgadget.dfu_function <magicvar_global_usbgadget_dfu_function>`
Function description for DFU. See :ref:`command_usbgadget` -D [desc],
and :ref:`usbgadget_partitions` above for the syntax.
-``global.fastboot.partitions``
+:ref:`global.fastboot.partitions <magicvar_global_fastboot_partitions>`
Function description for fastboot. See :ref:`command_usbgadget` -A [desc],
and :ref:`usbgadget_partitions` above for the syntax.
-``global.fastboot.bbu``
+:ref:`global.fastboot.bbu <magicvar_global_fastboot_bbu>`
Export barebox update handlers. See :ref:`command_usbgadget` -b. (Default 0).
diff --git a/Documentation/user/versioning.rst b/Documentation/user/versioning.rst
index d8e2fdbc4574..7da9766134d0 100644
--- a/Documentation/user/versioning.rst
+++ b/Documentation/user/versioning.rst
@@ -23,8 +23,9 @@ Query from barebox
When ``CONFIG_BANNER`` is enabled, the version information will be printed
to the console. From the shell, there is the
:ref:`version command <command_version>` for interactive use and the
-``global.version`` and ``global.buildsystem.version`` :ref:`magicvars`
-for use in scripts.
+:ref:`global.version <magicvar_global_version>` and
+:ref:`global.buildsystem.version <magicvar_global_buildsystem_version>`
+:ref:`magicvars` for use in scripts.
Query from OS
^^^^^^^^^^^^^
--
2.47.3
^ permalink raw reply [flat|nested] 9+ messages in thread