[PATCH] suricatta: Document suricatta's status mechanics
227 views
Skip to first unread message
Christian Storm
Aug 4, 2016, 10:48:22 AM8/4/16
to swup...@googlegroups.com, Christian Storm, Silvano Cirujano Cuesta
Suricatta needs to be aware of and relies on (externally set) states
in order to signal update success or failure to its server.
Improve the documentation of these states, their interplay, and their
semantics.
Signed-off-by: Christian Storm <christi...@tngtech.com>
Signed-off-by: Silvano Cirujano Cuesta <silvano.cir...@siemens.com>
---
doc/source/suricatta.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 79 insertions(+)
diff --git a/doc/source/suricatta.rst b/doc/source/suricatta.rst
index ccd4fb5..faa6e19 100644
--- a/doc/source/suricatta.rst
+++ b/doc/source/suricatta.rst
@@ -60,6 +60,85 @@ a hawkBit instance at ``http://10.0.0.2:8080`` with tenant ``default``
and device ID ``25``.
+Update Status Handling
+----------------------
+
+After having, e.g., installed an update and successfully rebooted into the
+new firmware, suricatta needs to be aware of this (success) status in order
+to communicate it to its server, e.g., hawkBit.
+
+Currently, given that ``CONFIG_SURICATTA_STATE_CHOICE_UBOOT`` is activated,
+the update status is stored persistently across reboots in U-Boot's
+environment in a variable specified by ``CONFIG_SURICATTA_STATE_UBOOT``. If
+U-Boot environment storage is not supported or activated, the ``--confirm``
+command line switch can be used to provide status information to suricatta.
+Suricatta has no means of its own to detect the update status, hence this
+information has to be provided to suricatta externally.
+
+There are five states as defined in ``include/suricatta/state.h``:
+
+- ``STATE_NOT_AVAILABLE``: normal operation w/o persistent storage backend
+- ``STATE_OK``: normal operation with persistent storage backend available
+- ``STATE_INSTALLED``: set by suricatta after having installed the update artifact(s)
+- ``STATE_TESTING``: externally set, e.g., by U-Boot, to signal "testing" status
+- ``STATE_FAILED``: externally set, e.g., by U-Boot, to signal "update failed" status
+
+When suricatta starts and reads ``STATE_OK`` or ``STATE_NOT_AVAILABLE``, it
+is in normal operation mode and periodically polls its server for updates.
+After having installed an update, suricatta sets ``STATE_INSTALLED``,
+signaling that the update has been installed so that the
+verification/testing phase can begin.
+This verification/testing has to be done by an external entity that sets
+``STATE_TESTING`` or, in case of failure while testing, ``STATE_FAILED``.
+
+For example, in case of using U-Boot's environment as storage backend and
+since, currently, suricatta unconditionally executes ``/bin/sh -c reboot``
+after installation, an U-Boot script lends itself to set ``STATE_TESTING``.
+If the newly flashed firmware cannot be booted successfully, a watchdog may
+reset the board and the U-Boot script sets ``STATE_FAILED`` accordingly
+prior to booting the old and known to work firmware.
+
+
+The next startup of suricatta marks the end of the verification/testing
+phase.
+If suricatta reads ``STATE_FAILED``, it reports update failure to its
+server, meaning the update or its verification/testing has failed.
+If suricatta reads ``STATE_TESTING``, it reports update success to its
+server, meaning the update and its verification/testing have been
+successful. Both terminate the current update operation on the server with
+respective outcomes and (re-)set the status to ``STATE_OK``.
+If suricatta reads ``STATE_INSTALLED``, the verification/testing phase
+hasn't been started as no externally induced status change has occurred.
+In this case, suricatta reports testing pending to its server, i.e., the
+current update operation is not terminated, and (re-)sets the status to
+``STATE_OK``. Hence, the very same update payload may be downloaded and
+installed subsequently, starting a new cycle.
+
+Supporting other Storage Backends
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Support for other persistent storage backends besides U-Boot's environment,
+e.g., file-based, could be implemented in ``suricatta/state.c``. There are
+three methods to implement, namely
+
+- ``server_op_res_t save_state(char *key, update_state_t value)``,
+- ``server_op_res_t read_state(char *key, update_state_t *value)``, and
+- ``server_op_res_t reset_state(char *key)``
+
+to save a key-value pair to the storage backend, to read a supplied key's
+value from the storage backend, and to unset/reset the key and value in
+the storage backend, respectively. Those three functions are to be called
+by a server implementation. See their usage in
+``suricatta/server_hawkbit.c`` for reference and example.
+The compile-time Kconfig-based selection of which storage backend to use
+should be integrated into ``suricatta/Config.in``.
+
+The ``enum`` ``update_state_t`` specifying the valid states as described
+above is defined in ``include/suricatta/state.h``.
+The ``enum`` ``server_op_res_t`` specifying the valid return codes is
+defined in ``include/suricatta/suricatta.h``.
+
+
Supporting different Servers
----------------------------
--
2.9.2
in order to signal update success or failure to its server.
Improve the documentation of these states, their interplay, and their
semantics.
Signed-off-by: Christian Storm <christi...@tngtech.com>
Signed-off-by: Silvano Cirujano Cuesta <silvano.cir...@siemens.com>
---
doc/source/suricatta.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 79 insertions(+)
diff --git a/doc/source/suricatta.rst b/doc/source/suricatta.rst
index ccd4fb5..faa6e19 100644
--- a/doc/source/suricatta.rst
+++ b/doc/source/suricatta.rst
@@ -60,6 +60,85 @@ a hawkBit instance at ``http://10.0.0.2:8080`` with tenant ``default``
and device ID ``25``.
+Update Status Handling
+----------------------
+
+After having, e.g., installed an update and successfully rebooted into the
+new firmware, suricatta needs to be aware of this (success) status in order
+to communicate it to its server, e.g., hawkBit.
+
+Currently, given that ``CONFIG_SURICATTA_STATE_CHOICE_UBOOT`` is activated,
+the update status is stored persistently across reboots in U-Boot's
+environment in a variable specified by ``CONFIG_SURICATTA_STATE_UBOOT``. If
+U-Boot environment storage is not supported or activated, the ``--confirm``
+command line switch can be used to provide status information to suricatta.
+Suricatta has no means of its own to detect the update status, hence this
+information has to be provided to suricatta externally.
+
+There are five states as defined in ``include/suricatta/state.h``:
+
+- ``STATE_NOT_AVAILABLE``: normal operation w/o persistent storage backend
+- ``STATE_OK``: normal operation with persistent storage backend available
+- ``STATE_INSTALLED``: set by suricatta after having installed the update artifact(s)
+- ``STATE_TESTING``: externally set, e.g., by U-Boot, to signal "testing" status
+- ``STATE_FAILED``: externally set, e.g., by U-Boot, to signal "update failed" status
+
+When suricatta starts and reads ``STATE_OK`` or ``STATE_NOT_AVAILABLE``, it
+is in normal operation mode and periodically polls its server for updates.
+After having installed an update, suricatta sets ``STATE_INSTALLED``,
+signaling that the update has been installed so that the
+verification/testing phase can begin.
+This verification/testing has to be done by an external entity that sets
+``STATE_TESTING`` or, in case of failure while testing, ``STATE_FAILED``.
+
+For example, in case of using U-Boot's environment as storage backend and
+since, currently, suricatta unconditionally executes ``/bin/sh -c reboot``
+after installation, an U-Boot script lends itself to set ``STATE_TESTING``.
+If the newly flashed firmware cannot be booted successfully, a watchdog may
+reset the board and the U-Boot script sets ``STATE_FAILED`` accordingly
+prior to booting the old and known to work firmware.
+
+
+The next startup of suricatta marks the end of the verification/testing
+phase.
+If suricatta reads ``STATE_FAILED``, it reports update failure to its
+server, meaning the update or its verification/testing has failed.
+If suricatta reads ``STATE_TESTING``, it reports update success to its
+server, meaning the update and its verification/testing have been
+successful. Both terminate the current update operation on the server with
+respective outcomes and (re-)set the status to ``STATE_OK``.
+If suricatta reads ``STATE_INSTALLED``, the verification/testing phase
+hasn't been started as no externally induced status change has occurred.
+In this case, suricatta reports testing pending to its server, i.e., the
+current update operation is not terminated, and (re-)sets the status to
+``STATE_OK``. Hence, the very same update payload may be downloaded and
+installed subsequently, starting a new cycle.
+
+Supporting other Storage Backends
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Support for other persistent storage backends besides U-Boot's environment,
+e.g., file-based, could be implemented in ``suricatta/state.c``. There are
+three methods to implement, namely
+
+- ``server_op_res_t save_state(char *key, update_state_t value)``,
+- ``server_op_res_t read_state(char *key, update_state_t *value)``, and
+- ``server_op_res_t reset_state(char *key)``
+
+to save a key-value pair to the storage backend, to read a supplied key's
+value from the storage backend, and to unset/reset the key and value in
+the storage backend, respectively. Those three functions are to be called
+by a server implementation. See their usage in
+``suricatta/server_hawkbit.c`` for reference and example.
+The compile-time Kconfig-based selection of which storage backend to use
+should be integrated into ``suricatta/Config.in``.
+
+The ``enum`` ``update_state_t`` specifying the valid states as described
+above is defined in ``include/suricatta/state.h``.
+The ``enum`` ``server_op_res_t`` specifying the valid return codes is
+defined in ``include/suricatta/suricatta.h``.
+
+
Supporting different Servers
----------------------------
--
2.9.2
Aravind Pavate
Oct 1, 2019, 6:58:26 AM10/1/19
to swupdate
Hi Christian Storm,
I am facing the issue of SWUpdate not reporting the success status back to the hawkbit server. After the successful download and installation. The state remains installed even after restarting the application or rebooting the device.
After restart of swupdate the installation begin again and it is never ending loop.
Request you to help me in this regard.
Aravind V Pavate
Christian Storm
Oct 7, 2019, 4:35:16 AM10/7/19
to swupdate
Hi Aravind,
> I am facing the issue of SWUpdate not reporting the success status back to
> the hawkbit server. After the successful download and installation. The
> state remains installed even after restarting the application or rebooting
> the device.
> After restart of swupdate the installation begin again and it is never
> ending loop.
Without detailed information, I suspect this is because SWUpdate is not
informed about the installation being successfully performed and thus does not
communicate the success back to hawkBit which is why the installation simply
restarts. SWUpdate needs the update status information, either from the
bootloader (e.g., U-Boot) or via command line, to communicate it to hawkBit in
order to close hawkBit's transaction.
Please review your setup in regard to this.
Kind regards,
Christian
> Request you to help me in this regard.
>
> Aravind V Pavate
>
> On Thursday, August 4, 2016 at 8:18:22 PM UTC+5:30, Christian Storm wrote:
> >
> > Suricatta needs to be aware of and relies on (externally set) states
> > in order to signal update success or failure to its server.
> > Improve the documentation of these states, their interplay, and their
> > semantics.
> >
> > Signed-off-by: Christian Storm <christi...@tngtech.com <javascript:>>
Besten Gruß,
Christian
--
Dr. Christian Storm
Siemens AG, Corporate Technology, CT RDA IOT SES-DE
Otto-Hahn-Ring 6, 81739 München, Germany
> I am facing the issue of SWUpdate not reporting the success status back to
> the hawkbit server. After the successful download and installation. The
> state remains installed even after restarting the application or rebooting
> the device.
> After restart of swupdate the installation begin again and it is never
> ending loop.
informed about the installation being successfully performed and thus does not
communicate the success back to hawkBit which is why the installation simply
restarts. SWUpdate needs the update status information, either from the
bootloader (e.g., U-Boot) or via command line, to communicate it to hawkBit in
order to close hawkBit's transaction.
Please review your setup in regard to this.
Kind regards,
Christian
> Request you to help me in this regard.
>
> Aravind V Pavate
>
> On Thursday, August 4, 2016 at 8:18:22 PM UTC+5:30, Christian Storm wrote:
> >
> > Suricatta needs to be aware of and relies on (externally set) states
> > in order to signal update success or failure to its server.
> > Improve the documentation of these states, their interplay, and their
> > semantics.
> >
> > Signed-off-by: Silvano Cirujano Cuesta <silvano.cir...@siemens.com
> > <javascript:>>
Christian
--
Dr. Christian Storm
Siemens AG, Corporate Technology, CT RDA IOT SES-DE
Otto-Hahn-Ring 6, 81739 München, Germany
Reply all
Reply to author
Forward
0 new messages