This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit e15baa5650cff5f0199169f0dbf2f066d2f191c6 Author: aviralgarg05 <[email protected]> AuthorDate: Fri Jul 24 15:10:33 2026 +0530 Documentation: Update nxpkg and add nxstore guide. Document nxpkg storage, repository metadata, lifecycle commands, recovery behavior, and transport trust limits. Add the companion nxstore guide, including installed-manifest launch behavior and the shared framebuffer supervisor-strip contract. Assisted-by: Claude:claude-sonnet-5 Assisted-by: OpenAI Codex:gpt-5.6-sol Signed-off-by: aviralgarg05 <[email protected]> --- Documentation/applications/system/nxpkg/index.rst | 154 +++++++++++++++++++++ .../applications/system/nxstore/index.rst | 91 ++++++++++++ 2 files changed, 245 insertions(+) diff --git a/Documentation/applications/system/nxpkg/index.rst b/Documentation/applications/system/nxpkg/index.rst new file mode 100644 index 00000000000..bc29faa01c8 --- /dev/null +++ b/Documentation/applications/system/nxpkg/index.rst @@ -0,0 +1,154 @@ +========= +``nxpkg`` +========= + +``nxpkg`` manages standalone Dynamic ELF application images in a small, +versioned on-device store. It can synchronize a static package catalog, +install or update a compatible payload, list available and installed +packages, roll back to the previous installed version, and remove a package. + +The implementation is intentionally small. It does not resolve dependencies +or provide a general-purpose system package format. + +Configuration +============= + +Enable ``CONFIG_SYSTEM_NXPKG``. The command name, task settings, and storage +root are configured with: + +* ``CONFIG_SYSTEM_NXPKG_PROGNAME`` +* ``CONFIG_SYSTEM_NXPKG_PRIORITY`` +* ``CONFIG_SYSTEM_NXPKG_STACKSIZE`` +* ``CONFIG_SYSTEM_NXPKG_ROOT`` + +The default storage root is ``/var/lib/nxpkg``. Mount persistent storage at +``/var`` or select a board-appropriate persistent path, such as +``/mnt/sdcard/nxpkg``, if installed packages must survive a reset. A +``tmpfs``-backed root is useful for tests but is not persistent. + +Dynamic ELF loading and the target's required binary-format support must also +be enabled. Synchronizing or downloading from an HTTP URL requires +``CONFIG_NETUTILS_WEBCLIENT`` and a working network configuration. Local +filesystem sources work without the web client. + +Commands +======== + +The command-line interface is: + +.. code-block:: console + + nxpkg sync <index-source> + nxpkg available + nxpkg install <name> + nxpkg update <name> + nxpkg list + nxpkg rollback <name> + nxpkg remove <name> + +``sync`` accepts either a local index path or an HTTP/HTTPS URL. ``install`` +selects the newest catalog entry whose architecture and compatibility strings +match the running target. ``update`` uses the same operation and therefore +installs the newest matching version. ``rollback`` swaps the current and +previous installed versions. + +Repository format +================= + +A repository is a directory of static files. No package-specific server is +required. Its index contains a ``packages`` array, for example: + +.. code-block:: json + + { + "packages": [ + { + "name": "hello", + "version": "1.0.0", + "arch": "xtensa", + "compat": "esp32s3-xiao", + "artifact": "artifacts/xtensa/esp32s3/esp32s3-xiao/hello/1.0.0/hello", + "sha256": "<64 hexadecimal characters>", + "type": "elf" + } + ] + } + +``name``, ``version``, ``arch``, ``compat``, ``artifact``, ``sha256``, and +``type`` are required. Supported types are ``elf`` and ``shared-lib``. +``description``, ``category``, ``icon``, and ``launch_args`` are optional +metadata used by front ends. Relative artifact and icon paths are resolved +from the synchronized index location. + +The catalog may contain entries for several targets and versions. Version +selection compares dot-separated numeric components numerically and other +components lexically; it is not a complete Semantic Versioning +implementation. + +The repository export helper in ``apps/tools/export_pkg_repo.py`` copies +built artifacts, calculates their SHA-256 digests, and writes the index: + +.. code-block:: console + + python3 apps/tools/export_pkg_repo.py /tmp/nxpkg-repo \ + --arch xtensa \ + --chip esp32s3 \ + --compat esp32s3-xiao \ + --package hello:1.0.0:elf:apps/bin/hello + +The resulting directory can be served during local development with any +static file server, for example: + +.. code-block:: console + + cd /tmp/nxpkg-repo + python3 -m http.server 8000 + +Then synchronize the board from the development host: + +.. code-block:: console + + nsh> nxpkg sync http://192.0.2.1:8000/index.json + nsh> nxpkg available + nsh> nxpkg install hello + nsh> nxpkg list + +Replace the example address with one reachable from the target. + +On-device layout +================ + +Under ``CONFIG_SYSTEM_NXPKG_ROOT``, ``nxpkg`` stores: + +* ``index.jsn``: the last synchronized catalog and the source used to resolve + relative artifact and icon paths +* ``instpkg.jsn``: the authoritative installed-package database +* ``pkgs/<name>/<version>/``: versioned payload and manifest files +* ``pkgs/<name>/current`` and ``previous``: convenience mirrors of the + database state +* ``tmp/``: bounded temporary downloads and atomic-write files + +Install and update operations use per-package locks. A separate lock +serializes changes to the shared installed database. An interrupted +operation leaves transaction state that the next operation can clean up. + +Security scope +============== + +The SHA-256 field detects accidental corruption only when the index itself is +trusted. If both the catalog and artifact arrive over unauthenticated HTTP, +an active attacker can replace both and provide a matching digest. Use an +authenticated transport and a trusted endpoint for untrusted networks. + +The current format does not include signed repository metadata or package +signatures. Plain HTTP is therefore appropriate only for a trusted, isolated +development network where that risk is explicitly accepted. Package +compatibility checks are target-selection checks, not a security boundary. + +Current limitations +=================== + +``nxpkg`` does not currently provide dependency solving, repository metadata +signatures, package signatures, or a policy engine. Filesystem constraints +also apply to the selected storage root; for example, a short-name-only FAT +configuration limits usable package and artifact names. diff --git a/Documentation/applications/system/nxstore/index.rst b/Documentation/applications/system/nxstore/index.rst new file mode 100644 index 00000000000..6154672a4d5 --- /dev/null +++ b/Documentation/applications/system/nxstore/index.rst @@ -0,0 +1,91 @@ +=========== +``nxstore`` +=========== + +``nxstore`` is an LVGL front end for :doc:`../nxpkg/index`. It displays the +packages in the synchronized catalog, installs a selected package on a worker +thread, launches installed Dynamic ELF applications, and supervises the one +application currently using the display. + +Configuration +============= + +Enable ``CONFIG_SYSTEM_NXSTORE``. It depends on +``CONFIG_GRAPHICS_LVGL`` and ``CONFIG_SYSTEM_NXPKG``. Its principal options +are: + +* ``CONFIG_SYSTEM_NXSTORE_PROGNAME`` +* ``CONFIG_SYSTEM_NXSTORE_PRIORITY`` +* ``CONFIG_SYSTEM_NXSTORE_STACKSIZE`` +* ``CONFIG_SYSTEM_NXSTORE_FBDEVPATH`` +* ``CONFIG_SYSTEM_NXSTORE_INPUT_DEVPATH`` + +The framebuffer and input paths default to ``/dev/fb0`` and ``/dev/input0``. +The board must provide LVGL-compatible display and input drivers. ``nxpkg`` +must use a writable storage root, and remote synchronization additionally +requires the networking options described in the ``nxpkg`` documentation. + +Starting the store +================== + +With no argument, ``nxstore`` opens the last catalog synchronized by +``nxpkg``: + +.. code-block:: console + + nsh> nxstore + +An optional index URL asks the store to synchronize before drawing the list: + +.. code-block:: console + + nsh> nxstore http://192.0.2.1:8000/index.json + +Transient network failures are retried for a bounded interval. If +synchronization still fails, the UI reports the failure and uses the last +valid cached catalog when one exists. Invalid metadata and local storage +errors are not retried. + +Interaction +=========== + +Each catalog package appears once, using its newest compatible version. + +* Tap an uninstalled package to install and launch it. +* Tap an installed package to launch its current installed version. +* Long-press an installed package to remove all its installed versions. +* Tap ``Close`` on the running-application screen to request termination. + +Installation runs outside the LVGL thread so progress remains visible. LVGL +objects are updated only by the main UI thread. Launch arguments are read +from the stored manifest for the current installed version, including after a +rollback. + +Application termination contract +================================ + +The ``Close`` control sends ``SIGTERM`` to the launched process. A +long-running application should install a signal handler that performs only +an async-signal-safe action, such as setting a ``volatile sig_atomic_t`` flag, +and then poll that flag from its main loop. The normal execution path should +release framebuffer, input, and other resources before returning. + +``nxstore`` does not force-delete an application that ignores ``SIGTERM``. +Forceful task deletion can interrupt display, heap, or filesystem operations +and leave the system in an unsafe state. Until the child exits, the store +keeps the running-application screen visible and does not hand the display +back to the package list. + +The store and the launched application share one framebuffer. A +framebuffer application must leave the top ``NXSTORE_BAR_HEIGHT`` pixels +untouched so the supervisor bar remains visible. Include +``<system/nxstore_chrome.h>`` instead of duplicating the current height. + +Current limitations +=================== + +Only one install worker and one supervised application are supported at a +time. The launcher currently uses one fixed, generous stack size for all +packages because the manifest format does not carry a per-application stack +requirement. Applications that cannot reserve the supervisor strip are not +currently suitable for launch from ``nxstore``.
