Documentation/nxinit: document boot reason property and compound cmds

Reviewers on apps#3751 (support compound command and resetcause-based
triggers) asked for documentation of the new features. Add two
sections to the nxinit doc:

- "Built-in Properties": describes the sys.boot.reason property set
  by NXInit at startup from BOARDIOC_RESET_CAUSE, its two value forms
  (hardware cause with numeric subreason, or software reset reason
  string), and behavior when CONFIG_BOARDCTL_RESET_CAUSE is disabled
  or the boardctl() call fails.
- "Compound Commands": describes the && / || short-circuit semantics
  for chaining commands on a single action line, including quoting
  behavior.

Assisted-by: GitHubCopilot:claude-sonnet-5
Signed-off-by: wangjianyu3 <wangjianyu3@xiaomi.com>
This commit is contained in:
wangjianyu3 2026-08-26 09:58:51 +08:00 committed by Alan C. Assis
parent 1f8c4bcaaf
commit 5f29325a44

View file

@ -89,6 +89,49 @@ forwards ``setprop`` to the action manager.
- Property triggers are checked when the property is created or its value
is updated (e.g., property:a=b is checked when a's value changes).
Built-in Properties
====================
NXInit sets one built-in property on its own, before the ``boot`` event
fires:
- ``sys.boot.reason``: the cause of the last board reset. It is queried
once at startup via ``boardctl(BOARDIOC_RESET_CAUSE, ...)``; applications
do not need to set it themselves. This requires
``CONFIG_BOARDCTL_RESET_CAUSE`` and a board-provided
``board_reset_cause()`` implementation.
- If ``CONFIG_BOARDCTL_RESET_CAUSE`` is not enabled, ``sys.boot.reason``
is never set, so any trigger referencing it (e.g.
``property:sys.boot.reason=...``) simply never matches; there is no
dedicated "unset" value to trigger on.
- If ``CONFIG_BOARDCTL_RESET_CAUSE`` is enabled but the ``boardctl()``
call itself fails (the board reports an error), NXInit aborts startup.
The value has one of two forms:
1. ``<cause>,<subreason>`` for hardware reset causes, where
``<subreason>`` is a numeric flag (e.g. the watchdog timer index):
``cold``, ``watchdog``, ``undervoltage``, ``warm``, ``powerkey``,
``lowpower``, ``unknown``. For example, a watchdog reset from timer 4
sets the property to ``watchdog,4``.
2. A single soft-reset reason string, for software-triggered resets
(``BOARDIOC_RESETCAUSE_CPU_SOFT``): ``reboot``, ``assert``,
``kernel_panic``, ``bootloader``, ``recovery``, ``factory_reset``,
``factory_reset_inquiry``, ``thermal``.
Since the property is matched with ``fnmatch`` and alternatives can be
separated with ``|``, a trigger can match on the cause, the subreason, or
a set of soft-reset reasons:
.. code-block::
on init && property:sys.boot.reason=watchdog,4
...
on init && property:sys.boot.reason=bootloader|recovery|thermal
...
Commands
========
The commands supported by an action fall into three types: the built-in
@ -105,6 +148,24 @@ The following is an explanation of some of NXInit's built-in commands.
owner, and encryption settings), copy/write (copy files/write file content).
- Others: trigger (trigger events).
Compound Commands
------------------
A single line inside an action body may chain multiple commands with
``&&`` and ``||``, using the familiar shell short-circuit semantics: the
next command in an ``&&`` chain only runs if the previous one exited with
status 0 (success), and the next command in an ``||`` chain only runs if
the previous one exited non-zero (failure). A quoted argument
(``"..."``) may contain ``&&``/``||`` without being treated as an
operator.
.. code-block::
on boot
echo "start" && hello && echo "done"
ls /missing || echo "not found"
echo "A" && echo "B" || echo "fallback"
Examples
========
This is an example of enabling the basic functions of the NXInit component,