This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 5f29325a447 Documentation/nxinit: document boot reason property and
compound cmds
5f29325a447 is described below
commit 5f29325a4474af4e4a5dd1599e323b60e1297a4d
Author: wangjianyu3 <[email protected]>
AuthorDate: Wed Aug 26 09:58:51 2026 +0800
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 <[email protected]>
---
Documentation/applications/system/nxinit/index.rst | 61 ++++++++++++++++++++++
1 file changed, 61 insertions(+)
diff --git a/Documentation/applications/system/nxinit/index.rst
b/Documentation/applications/system/nxinit/index.rst
index 37861f1daac..4f59b4ceeb6 100644
--- a/Documentation/applications/system/nxinit/index.rst
+++ b/Documentation/applications/system/nxinit/index.rst
@@ -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,
