[PATCH] doc: cmd: wget: document lwIP syntax

[Ilias Apalodimas]

Hi Jerome

+CC Simon, since he asked for an update on the docs

On Thu, 14 Nov 2024 at 16:20, Jerome Forissier <jerome.forissier at linaro.org>
wrote:

> The lwIP version of wget supports a different syntax with a URL,
> in addition to the legacy syntax. Document that.
>
> While we're at it, fix a couple of minor issues in the legacy
> syntax:
> - hostIPaddr can be an IP address or a DNS name
> - path is mandatory
>
> Signed-off-by: Jerome Forissier <jerome.forissier at linaro.org>
> ---
>  doc/usage/cmd/wget.rst | 71 +++++++++++++++++++++++++++++++++++-------
>  1 file changed, 60 insertions(+), 11 deletions(-)
>
> diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst
> index b8ca35bb140..5be01a22e47 100644
> --- a/doc/usage/cmd/wget.rst
> +++ b/doc/usage/cmd/wget.rst
> @@ -11,29 +11,51 @@ Synopsis
>
>  ::
>
> -    wget address [[hostIPaddr:]path]
> +    wget [address] [host:]path
> +    wget [address] url          # lwIP only
> +
>
>  Description
>  -----------
>
> -The wget command is used to download a file from an HTTP server.
> +The wget command is used to download a file from an HTTP(S) server.
> +In order to use HTTPS you will need to compile wget with lwIP support.
> +
> +Legacy syntax
> +~~~~~~~~~~~~~
> +
> +The legacy syntax is supported with the legacy network stack as well as
> +lwIP. It allows only HTTP.
>
> -wget command will use HTTP over TCP to download files from an HTTP server.
>  By default the destination port is 80 and the source port is
> pseudo-random.
> -The environment variable *httpdstp* can be used to set the destination
> port.
> +The environment variable *httpdstp* can be used to set the destination
> port
> +(legacy nework stack only).
>
>  address
>      memory address for the data downloaded
>
> -hostIPaddr
> -    IP address of the HTTP server, defaults to the value of environment
> -    variable *serverip*
> +host
> +    IP address or DNS name of the HTTP server, defaults to the value of
> +    environment variable *serverip*.
>
>  path
>      path of the file to be downloaded.
>
> -Example
> --------
> +
> +New syntax (lwIP only)
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +In addition to the syntax described above, wget accepts URLs if the
> network
> +stack is lwIP.
> +
> +address
> +    memory address for the data downloaded
> +
> +url
> +    HTTP or HTTPS URL, that is: http[s]://<host>[:<port>]/<path>.
> +
> +Example with the legacy network stack
> +-------------------------------------
>
>  In the example the following steps are executed:
>
> @@ -52,13 +74,40 @@ In the example the following steps are executed:
>      HTTP/1.0 302 Found
>      Packets received 4, Transfer Successful
>
> +Example with lwIP
> +-----------------
> +
> +In the example the following steps are executed:
> +
> +* setup client network address
> +* download a file from the HTTPS server
> +
> +::
> +
> +   => dhcp
> +   DHCP client bound to address 10.0.2.15 (3 ms)
> +   => wget
> https://download.rockylinux.org/pub/rocky/9/isos/aarch64/Rocky-9.4-aarch64-minimal.iso
> +
>  ##########################################################################
> +
>  ##########################################################################
> +
>  ##########################################################################
> +   [...]
> +   1694892032 bytes transferred in 492181 ms (3.3 MiB/s)
> +   Bytes transferred = 1694892032 (65060000 hex)
> +
>  Configuration
>  -------------
>
>  The command is only available if CONFIG_CMD_WGET=y.
> +To enable lwIP support set CONFIG_NET_LWIP=y.
>
> -TCP Selective Acknowledgments can be enabled via CONFIG_PROT_TCP_SACK=y.
> -This will improve the download speed.
> +TCP Selective Acknowledgments in the legacy network stack can be enabled
> via
> +CONFIG_PROT_TCP_SACK=y. This will improve the download speed. Selective
> +Acknowledgments are enabled by default with lwIP.
> +
> +**Note**: U-Boot currently has no way to verify certificates for HTTPS.
> +A place to store the root CA certificates is needed, and then MBed TLS
> would
> +need to walk the entire chain. Therefore, man-in-the middle attacks are
> +possible and HTTPS should not be relied upon for payload authentication.
>
>  Return value
>  ------------
> --
> 2.40.1
>
>
 Reviewed-by: Ilias Apalodimas <ilias.apalodimas at linaro.org>