.. SPDX-FileCopyrightText: 2013-2021 Stefano Babic <sbabic@denx.de>
.. SPDX-License-Identifier: GPL-2.0-only

Getting information on running update
=====================================

It is often required to inform the operator about the status of the running
update and not just to return if the update was successful or not.
For example, if the target has a display or a remote interface,
it can be forwarded which is reached percentage of the update
to let estimate how much the update will still run.
SWUpdate has an interface for this ("progress API"). An external
process can register itself with SWUpdate, and it will receive
notifications when something in the update was changed. This is
different from the IPC API, because the last one is mainly used to transfer
the SWU image, and it is only possible to poll the interface to know
if the update is still running.


API Description
---------------

An external process registers itself to SWUpdate with a connect()
request to the domain socket "/tmp/swupdateprog" as per default
configuration of SWUpdate. There is no information to send, and
SWUpdate simply inserts the new connection into the list of processes
to be informed. SWUpdate will send a frame back after any change in
the update process with the following data (see include/progress_ipc.h):

::

        struct progress_msg {
        	unsigned int	magic;		/* Magic Number */
        	unsigned int	status;		/* Update Status (Running, Failure) */
        	unsigned int	dwl_percent;	/* % downloaded data */
        	unsigned long long dwl_bytes;   /* total of bytes to be downloaded */
        	unsigned int	nsteps;		/* No. total of steps */
        	unsigned int	cur_step;	/* Current step index */
        	unsigned int	cur_percent;	/* % in current step */
        	char		cur_image[256];	/* Name of image to be installed */
        	char		hnd_name[64];	/* Name of running handler */
        	sourcetype	source;		/* Interface that triggered the update */
        	unsigned int 	infolen;    	/* Len of data valid in info */
        	char		info[2048];   	/* additional information about install */
        };

The single fields have the following meaning:

        - *magic* is not yet used, it could be added for simply verification of the frame.
        - *status* is one of the values in swupdate_status.h (START, RUN, SUCCESS, FAILURE, DOWNLOAD, DONE).
        - *dwl_percent* is the percentage of downloaded data when status = DOWNLOAD.
        - *dwl_bytes* is the total number of bytes that are to be downloaded.
        - *nsteps* is the total number of installers (handlers) to be run.
        - *cur_step* is the index of the running handler. cur_step is in the range 1..nsteps
        - *cur_percent* is the percentage of work done inside the current handler. This is useful
          when updating a slow interface, such as a slow flash, and signals which is the percentage
          of image already copied into the destination.
        - *cur_image* is the name of the image in sw-description that is currently being installed.
        - *hnd_name* reports the name of the running handler.
        - *source* is the interface that triggered the update.
        - *infolen* length of data in the following info field.
        - *info* additional information about installation.


As an example for a progress client, ``tools/swupdate-progress.c`` prints the status
on the console and drives "psplash" to draw a progress bar on a display.