Extend the firmware loader subsystem to support a persistent sysfs
interface that userspace may use to initiate a firmware update. For
example, FPGA based PCIe cards automatically load firmware and FPGA images
from local FLASH when the card boots. The images in FLASH may be updated
with new images that are uploaded by the user.

A device driver may call fw_upload_register() to expose persistent
"loading" and "data" sysfs files at /sys/class/firmare/<NAME>/*. These
files are used in the same way as the fallback sysfs "loading" and "data"
files. However, when 0 is written to "loading" to complete the write of
firmware data, the data is also transferred to the lower-level driver
using pre-registered call-back functions. The data transfer is done in
the context of a kernel worker thread.

Additional sysfs nodes are added in the same location as "loading" and
"data" to monitor the transfer of the image data to the device using
callback functions provided by the lower-level device driver and to allow
the data transfer to be cancelled.

Example usage:

$ pwd
/sys/class/firmware/n3000bmc-sec-update.8
$ ls
cancel  device  loading  remaining_size  subsystem
data    error   power    status          uevent
$ echo 1 > loading
$ cat /tmp/firmware.bin > data
$ echo 0 > loading
$ while :; do cat status; cat remaining_size ; sleep 3; done
preparing
44590080
<--snip-->
transferring
44459008
transferring
44311552
<--snip-->
<snip>
transferring
173056
<--snip-->
programming
0
<--snip-->
idle
0
^C

The first two patches in this set make minor changes to enable the
fw_priv data structure and the sysfs interfaces to be used multiple times
during the existence of the device driver instance. The third patch is
mostly a reorganization of existing code in preparation for sharing common
code with the firmware-upload support. The final two patches provide the
code for user-initiated firmware uploads.

This driver was previously submitted in the context of the FPGA sub-
system as the "FPGA Image Load Framework", but the framework is generic
enough to support other devices as well. The previous submission of this
patch-set can be viewed here:

https://marc.info/?l=linux-kernel&m=163295640216820&w=2

The n3000bmc-sec-update driver is the first driver to use the Firmware
Upload API. A recent version of these patches can be viewed here:

https://marc.info/?l=linux-kernel&m=163295697217095&w=2

- Russ

Russ Weight (5):
  firmware_loader: Clear data and size in fw_free_paged_buf
  firmware_loader: Check fw_state_is_done in loading_store
  firmware_loader: Split fw_sysfs support from fallback
  firmware_loader: Add firmware-upload support
  firmware_loader: Add sysfs nodes to monitor fw_upload

 .../ABI/testing/sysfs-class-firmware          |  77 +++
 .../driver-api/firmware/fw_upload.rst         | 103 ++++
 Documentation/driver-api/firmware/index.rst   |   1 +
 drivers/base/firmware_loader/Kconfig          |  18 +
 drivers/base/firmware_loader/Makefile         |   2 +
 drivers/base/firmware_loader/fallback.c       | 430 ----------------
 drivers/base/firmware_loader/fallback.h       |  46 +-
 drivers/base/firmware_loader/firmware.h       |  11 +
 drivers/base/firmware_loader/fw_sysfs.c       | 468 ++++++++++++++++++
 drivers/base/firmware_loader/fw_sysfs.h       |  98 ++++
 drivers/base/firmware_loader/fw_upload.c      | 348 +++++++++++++
 drivers/base/firmware_loader/fw_upload.h      |  29 ++
 drivers/base/firmware_loader/main.c           |  18 +-
 include/linux/firmware.h                      |  72 +++
 14 files changed, 1236 insertions(+), 485 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-class-firmware
 create mode 100644 Documentation/driver-api/firmware/fw_upload.rst
 create mode 100644 drivers/base/firmware_loader/fw_sysfs.c
 create mode 100644 drivers/base/firmware_loader/fw_sysfs.h
 create mode 100644 drivers/base/firmware_loader/fw_upload.c
 create mode 100644 drivers/base/firmware_loader/fw_upload.h

-- 
2.25.1

On Thu, Feb 03, 2022 at 02:30:47PM -0700, Russ Weight wrote:
> Extend the firmware loader subsystem to support a persistent sysfs
> interface that userspace may use to initiate a firmware update. For
> example, FPGA based PCIe cards automatically load firmware and FPGA images
> from local FLASH when the card boots. The images in FLASH may be updated
> with new images that are uploaded by the user.
> 
> A device driver may call fw_upload_register() to expose persistent
> "loading" and "data" sysfs files at /sys/class/firmare/<NAME>/*. These
> files are used in the same way as the fallback sysfs "loading" and "data"
> files. However, when 0 is written to "loading" to complete the write of
> firmware data, the data is also transferred to the lower-level driver
> using pre-registered call-back functions. The data transfer is done in
> the context of a kernel worker thread.
> 
> Additional sysfs nodes are added in the same location as "loading" and
> "data" to monitor the transfer of the image data to the device using
> callback functions provided by the lower-level device driver and to allow
> the data transfer to be cancelled.
> 
> Example usage:
> 
> $ pwd
> /sys/class/firmware/n3000bmc-sec-update.8
> $ ls
> cancel  device  loading  remaining_size  subsystem
> data    error   power    status          uevent
> $ echo 1 > loading
> $ cat /tmp/firmware.bin > data
> $ echo 0 > loading
> $ while :; do cat status; cat remaining_size ; sleep 3; done
> preparing
> 44590080
> <--snip-->
> transferring
> 44459008
> transferring
> 44311552
> <--snip-->
> <snip>
> transferring
> 173056
> <--snip-->
> programming
> 0
> <--snip-->
> idle
> 0
> ^C

Nice. Please extend lib/test_firmware.c while at it and try to break
and ensure your stuff is not regressed with future changes.

  Luis

On 2/3/22 3:00 PM, Luis Chamberlain wrote:
> On Thu, Feb 03, 2022 at 02:30:47PM -0700, Russ Weight wrote:
>> Extend the firmware loader subsystem to support a persistent sysfs
>> interface that userspace may use to initiate a firmware update. For
>> example, FPGA based PCIe cards automatically load firmware and FPGA images
>> from local FLASH when the card boots. The images in FLASH may be updated
>> with new images that are uploaded by the user.
>>
>> A device driver may call fw_upload_register() to expose persistent
>> "loading" and "data" sysfs files at /sys/class/firmare/<NAME>/*. These
>> files are used in the same way as the fallback sysfs "loading" and "data"
>> files. However, when 0 is written to "loading" to complete the write of
>> firmware data, the data is also transferred to the lower-level driver
>> using pre-registered call-back functions. The data transfer is done in
>> the context of a kernel worker thread.
>>
>> Additional sysfs nodes are added in the same location as "loading" and
>> "data" to monitor the transfer of the image data to the device using
>> callback functions provided by the lower-level device driver and to allow
>> the data transfer to be cancelled.
>>
>> Example usage:
>>
>> $ pwd
>> /sys/class/firmware/n3000bmc-sec-update.8
>> $ ls
>> cancel  device  loading  remaining_size  subsystem
>> data    error   power    status          uevent
>> $ echo 1 > loading
>> $ cat /tmp/firmware.bin > data
>> $ echo 0 > loading
>> $ while :; do cat status; cat remaining_size ; sleep 3; done
>> preparing
>> 44590080
>> <--snip-->
>> transferring
>> 44459008
>> transferring
>> 44311552
>> <--snip-->
>> <snip>
>> transferring
>> 173056
>> <--snip-->
>> programming
>> 0
>> <--snip-->
>> idle
>> 0
>> ^C
> Nice. Please extend lib/test_firmware.c while at it and try to break
> and ensure your stuff is not regressed with future changes.
Yes. I'm looking at the test_firmware module and I'll add to it
for the next patch submission.

Thanks,
- Russ
>
>   Luis