lvfs: Initial release for LVFS. (#152)

- Add documentation on how to flash using fwupdtool - Add documentation on how to flash latest release on LVFS using fwupdmgr - Add documentation on how to restore from a backup Co-authored-by: Will Springer <[email protected]>
meklort · Oct 27, 2020 · c91b2e9 · c91b2e9
1 parent 1c5f20b
commit c91b2e9
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,11 @@
 # BCM5719 Firmware Reimplementation
-
-## Introduction
-This library contains a clean-room reimplementation of the BCM5719 firmware based on the [Ortega](https://github.com/hlandau/ortega/blob/master/rtg-spec.md) specification.
+This project contains a clean-room reimplementation of the BCM5719 firmware based on the [Ortega](https://github.com/hlandau/ortega/blob/master/rtg-spec.md) specification.
 
 The firmware has been tested on the [Talos II](https://wiki.raptorcs.com/wiki/Talos_II) and [Blackbird](https://wiki.raptorcs.com/wiki/Blackbird) made by [Raptor Computer Systems](https://www.raptorcs.com/).
 
 **Note: This firmware is currently in development. Flashing the firmware to a network card can result in a bricked device when either an external programmer is required, or the external flash must be temporarily disabled during boot-up.**
 
-## Status
+# Status
 The current version of the code is functional and is able to handle network traffic over NC-SI.
   - Libraries:
     - MII Library: Done
@@ -27,38 +25,43 @@ The current version of the code is functional and is able to handle network traf
     - Register tool: Functional
   - Tests: To be written
 
-## Usage
-The paths in the steps below refer to the release archives. Files in the development tree (after following instructions in [Building](#building)) are located in subdirectories of `./build`.
+# Usage
+Blackbird and Talos II users may install this firmware using [fwupd](https://fwupd.org/), either via the Linux Vendor Firmware Service, or manually using `fwupdtool` and a [release archive](https://github.com/meklort/bcm5719-fw/releases). Other BCM5719 devices may not be thoroughly tested, or tested at all; should you wish to proceed, it is encouraged to download or [build](#building) the firmware and refer to instructions in [Development](#development), especially the section on [testing APE firmware](#testing-ape-firmware).
 
-### Backup Firmware
-Before proceeding, the original firmware should be backed up.
+## Installing using LVFS
+This project provides firmware releases on LVFS that can be installed using fwupd 1.5.0 or later.
+The firmware can be selected for install by following the prompts using the `switch-branch` command in `fwupdmgr`:
 ```bash
-sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -b binary
+sudo fwupdmgr switch-branch
 ```
-This will result in a firmware image, firmware.fw, being stored in the current directory.
 
-### Stage 1 - MIPS Firmware
-The MIPS firmware can be loaded into the device as follows:
-```bash
-sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -1 fw/stage1.bin
-```
+This will flash the latest firmware from LVFS onto the network card and will save a backup of the previous firmware in `/var/lib/fwupd/backup/`.
 
-### APE Firmware (BMC/NC-SI communication)
-Following application of Stage 1, the APE firmware can be flashed. 
+Once switched, future releases will be installed using the standard update mechanism in fwupd.
+
+## Installing using fwupdtool
+Alternatively to using LVFS, the fwupd cab files in the release package can be manually flashed with `fwupdtool` 1.5.0 or later.
 
 For **Talos II**:
 ```bash
-sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -a fw/ape-port0.bin
+sudo fwupdtool install ./fwupd/talos2-bcm5719-<version>.cab --allow-branch-switch
 ```
-
 For **Blackbird**:
 ```bash
-sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -a fw/ape-port2.bin
+sudo fwupdtool install ./fwupd/blackbird-bcm5719-<version>.cab --allow-branch-switch
 ```
 
-Other BCM5719 devices are not tested, so the APE firmware should first be [loaded into RAM](#testing-ape-firmware) to test.
+## Restoring From Backup
+Past firmware images can be restored from backup using the bcmflash tool.
+* If fwupd was used to flash firmware, past backups can be located at `/var/lib/fwupd/backup/`.
+* If `bcmflash` was used to [create a backup](#backup-firmware) the previously saved `firmware.fw` should be used.
+
+To restore a backup, the following command can be run:
+```bash
+sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -r firmware.fw
+```
 
-## Building
+# Building
 
 ### Requirements
 This repository depends on a number of external tools
@@ -90,8 +93,8 @@ cd build
 cmake .. -G Ninja
 cmake --build .
 ```
-## Development
 
+## Development
 To access the APE console, test APE firmware in RAM, etc., the Linux `tg3` driver must be unbound from at least one PCIe function of the NIC. Each function corresponds to a single Ethernet port; for instance, the Talos II has `0004:01:00.0` and `0004:01:00.1`, while the Blackbird additionally has `0004:01:00.2`. Unbinding will disable the corresponding `enP4p1s0f#` network adapter.
 
 A function can be unbound via sysfs as follows:
@@ -103,6 +106,8 @@ Rebinding is similar, except that the address is written to `bind` instead of `u
 
 Unbinding a function allows `bcmflash` to access the device via `-t raw`, which is used with the `-i` option to select the function number to use.
 
+Binding a function allows `bcmflash` to access the device via `-t eth`, with is used with the `-i` option to select the ethernet interface to use.
+
 ### Testing APE firmware
 
 After unbinding the driver per the above, the APE firmware can be tested by loading it into RAM using the following sequence (note that this may fail if stage1 has not been loaded):
@@ -123,3 +128,27 @@ sudo ./utils/bcmregtool/bcmregtool --apeboot=ape/ape-port2.bin
 The APE and Stage1 firmware are able to print status messages to a log. This can be accessed in one of two ways:
  * The ./utils/apeconsole/apeconsole utility can be used if no driver is loaded by the host.
  * The EM100Pro console can be used if wired to the SPI bus on the BCM5719. This allows for printouts even when the host is off.
+
+## Backup Firmware
+Before altering the BCM5719 flash, the original firmware should be backed up using `bcmflash` and the appropriate `-t` and `-i` options as described in [Development](#Development)
+
+```bash
+cd build
+sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -b binary
+```
+This will result in a firmware image, `firmware.fw`, being stored in the current directory.
+
+## Flashing Firmware with bcmflash
+The flash can be updated with development firmware using `bcmflash` and the appropriate `-t` and `-i` options as described in [Development](#Development)
+
+### Updating the MIPS Firmware
+```bash
+cd build
+sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -1 stage1/stage1.bin
+```
+
+### Updating the APE Firmware
+```bash
+cd build
+sudo ./bin/bcmflash -t eth -i enP4p1s0f0 -a ape/ape-port0.bin
+```
diff --git a/fwupd/changelog.cmake b/fwupd/changelog.cmake
@@ -43,7 +43,7 @@
 ################################################################################
 
 # List all topics here that should be included in the release notes.
-SET(FWUPD_TOPICS APE Stage1)
+SET(FWUPD_TOPICS LVFS APE Stage1)
 
 # Convert to lower case while preserving original case.
 FOREACH(TOPIC IN LISTS FWUPD_TOPICS)

diff --git a/fwupd/metainfo.xml.in b/fwupd/metainfo.xml.in
@@ -7,7 +7,7 @@
     <branch>oss-firmware</branch>
     <description>
         <p>
-            This is an alternate firmware built by the community using only free
+            This is alternate firmware built by the community using only free
             software tools.
         </p>
     </description>