This API is used by privileged apps to control the software update process. It can be used to:

prevent updates from happening or
control the marking of a system update as "good" or "bad".

Note that this is not part of the Update API (le_update) because the Update API can be used by less trusted apps to feed signed/encrypted updates to the Update Daemon, and we may not trust those same apps to have the ability to prevent someone else from updating or rolling-back the system.

Preventing Updates During Critical Operations

To protect against updates during critical periods of operation (such as when performing an emergency call in response to a vehicle collision), the following functions are provided:

le_updateCtrl_Defer() - prevent all updates until further notice.
le_updateCtrl_Allow() - allow updates to go ahead.

Updates will not be allowed to go ahead until no clients are deferring updates. So, if client A and client B both call le_updateCtrl_Defer(), updates will be deferred until both client A and client B have called le_updateCtrl_Allow().

le_updateCtrl_Defer() will also prevent rollbacks unless a fault triggers the Supervisor to restart the framework or reboot the target. See below for more information on rollbacks.

Controlling the Probation Period

Whenever a new system is started, a probation period begins. If the system stays running for the entire probation period, the system is marked "good". But, during the probation period, if an app faults enough times in a short enough period for the Supervisor to give up on trying to start it, the system update is marked "bad" and the system is rolled-back to the last known "good" system.

In some cases, a customer may want to extend the probation period of their new system for a non-deterministic amount of time, until it has had a chance to perform some action in the real world (such as successfully "phoning home" at least once).

To support this, the functions le_updateCtrl_LockProbation() and le_updateCtrl_UnlockProbation() are provided, where each call to "Lock" must be matched with a call to "Unlock".

For those who want to mark "good" at some point of their own determination, regardless of how long the system has been up, le_updateCtrl_MarkGood() is provided.

And for those who want to mark the system "bad" and trigger a rollback at some point of their own choosing, le_updateCtrl_FailProbation() is provided.

Calls to any of the functions that affect the probation period are ignored if the probation period is already over (if the system is already marked "good"). Once it is "good", it stays "good".

If someone tries to update the system while it is still in its probation period, the update will be refused. To override this, call le_updateCtrl_FailProbation() or le_updateCtrl_MarkGood() to end the probation period before trying to apply the new system update.

Note: If a reboot occurs during the probation period, the probation period will start over. But, if the system reboots more than a few times without reaching the end of its probation period first, then the system will be rolled-back to the last known "good" system.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.