mirror of
https://github.com/apache/nuttx.git
synced 2026-08-27 04:10:40 +00:00
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:
parent
1f8c4bcaaf
commit
5f29325a44
1 changed files with 61 additions and 0 deletions
|
|
@ -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,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue