Merge branch 'gateware-upgrade' into 'main'

BeagleV-Fire: Add description of gateware upgrade.

See merge request docs/docs.beagleboard.io!101

boards/beaglev/fire/02-quick-start.rst

@@ -93,6 +93,7 @@ Demos and Tutorials
 *******************
 
 * :ref:`beaglev-fire-gateware-version`
+* :ref:`beaglev-fire-upgrade-gateware`
 * :ref:`beaglev-fire-flashing-board`
 * :ref:`beaglev-fire-gateware-design`
 * :ref:`beaglev-fire-mchp-fpga-tools-installation-guide`

boards/beaglev/fire/05-demos.rst

@@ -14,6 +14,7 @@ Demos
 .. toctree:: 
     :maxdepth: 1
     
+    demos-and-tutorials/gateware/upgrade-gateware
     demos-and-tutorials/flashing-board
     demos-and-tutorials/mchp-fpga-tools-installation-guide
     demos-and-tutorials/gateware/index

boards/beaglev/fire/demos-and-tutorials/gateware/upgrade-gateware.rst

+.. _beaglev-fire-upgrade-gateware:
+
+Upgrade BeagleV-Fire Gateware
+####################################
+
+This document describes how to upgrade your BeagleV-Fire's gateware. This approach can be used out
+of the box using Linux commands executed on BeagleV-Fire
+
+Required Equipment
+********************
+- BeagleV-Fire board
+- USB-C cable
+- Ethernet cable
+
+The USB-C cable provides power, a serial interface to BeagleV-Fire and allows connecting to
+BeagleV-Fire through a browser using IP address ``192.168.7.2``.
+
+The Ethernet cable connected to your local network (LAN) allows connecting to BeagleV-Fire using
+the SSH protocol. It also allows BeagleV-Fire to retrieve updated packages through your local
+network's Internet connection.
+
+Connect to BeagleV-Fire Linux Command Line Interface
+*****************************************************
+BeagleV-Fire boots Linux out of the box. Like all Beagleboard boards there are several methods to
+get BeagleV-Fire's Linux command prompt.
+
+- Cockpit
+- SSH
+- Serial port
+
+Cockpit
+========
+
+Enter the following URL in your web browser: ``https://beaglev.localdomain:9090/``
+
+On first use, click through the security warning. Login using ``beagle/temppwd`` as user/password.
+Click on Terminal in the left pane. You now have a Linux command prompt running on your
+BeagleV-Fire. Next step: enter the commands described in the Gateware Upgrade Linux Commands
+section of this document.
+
+.. note::
+    
+    You can connect to the Cockpit using the IP address dynamically assigned to your
+    BeagleV-Fire in your local Ethernet network. One method of finding the value of that
+    dynamically assigned IP address is to open a serial terminal though the USB port and use the
+    ``ip address`` Linux command. Please refer to the USB Serial Port section.
+
+SSH
+====
+
+Like all Beagleboard boards, you can SSH to the board through the USB interface by using IP
+address 192.168.7.2.
+
+.. note::
+    
+    On Windows, this approach may require some drivers to be updated or installed. Use one of the
+    other approaches if you are not immediately successful with this one. You can circle back later
+    to adjust your Windows installation if required.
+
+Serial Port
+================
+
+A serial port is available through the USB-C port. This serial port becomes available once Linux
+has booted on BeagleV-Fire. Please wait a couple of minutes after powering up the board before
+looking for additional serial ports reported by your host computer's operating system. You can then
+use your favorite serial port terminal tool such as Putty or Screen to access the BeagleV-Fire
+Linux command prompt.
+
+For example on your Linux host computer:
+
+.. code-block:: shell
+
+    screen /dev/ttyACM0 115200
+
+Where ``ttyACM0`` is an additional serial port that appeared after BeagleV-Fire was connected to
+your Linux host computer. This serial port can be identified using the ``dmesg | grep tty`` Linux
+command which will show the most recent serial port added to the host computer.
+
+On Windows, BeagleV-Fire's serial port number will show in the Windows Device Manager. Use that
+serial port number in Putty with a speed 115200 baud, no flow-control.
+
+Gateware Upgrade Linux Commands
+********************************
+
+.. note::
+    
+    BeagleV-Fire needs to be connected to the internet through your local network for the commands
+    in this section to work. The connection can be through the Ethernet port or the Wi-Fi module.
+
+Install bbb.io-gateware
+========================
+
+You need to install the bbb.io-gateware package. This will allow retrieving the most up-to-date
+gateware.
+
+.. code-block:: shell
+
+    sudo apt install bbb.io-gateware
+
+Retrieve Available Updated Linux packages List
+===============================================
+
+The list will include the latest BeagleV-Fire gateware packages.
+
+.. code-block:: shell
+
+    sudo apt update
+
+Upgrade Linux Packages
+=======================
+
+This will upgrade the BeagleV-Fire gateware Linux programming files located
+under ``/usr/share/beagleboard/gateware``. Several directories are found in that location, each
+containing programming files for one individual gateware configuration.
+
+.. code-block:: shell
+
+    sudo apt upgrade
+
+Launch Reprogramming of BeagleV-Fire's FPGA
+============================================
+
+Change directory to ``/usr/share/beagleboard/gateware``. This directory contains a script
+performing the gateware's reprogramming. It also contains one directory for each of the possible
+gateware configuration that can be programmed into your BeagleV-Fire. The name of one of these
+directories is passed as argument to the script to specify which gateware configuration you wish to
+program your BeagleV-Fire with.
+
+.. code-block:: shell
+
+    cd /usr/share/beagleboard/gateware
+    . ./change-gateware.sh default
+
+.. important:: 
+    Do not power-off BeagleV-Fire until it has rebooted by itself. The gateware reprogramming may
+    take a couple of minutes.
+    
+The change-gateware script programs the selected gateware and its associated device tree overlays
+into the PolarFire SoC System Controllers SPI flash and triggers a software reboot. During the
+reboot, the Hart Software Services (HSS) will request the PolarFire SoC System Controller to
+reprogram the FPGA and eNVM. The PolarFire SoC System Controller will reprogram the FPGA if it
+finds it contains a different design version than the one in the SPI Flash. The board reboots on
+completion of the FPGA reprogramming.