Skip to contentSkip to conversation

docs: driver-api: firmware: add driver firmware guidelines.

PATCH In review Dave Airlie 6 participants 8 messages Jul 18, 2022 – Jul 19, 2022

Subsystems (5)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: driver-api: firmware: add driver firmware guidelines.

From: Dave Airlie <[email protected]>

A recent snafu where Intel ignored upstream feedback on a firmware change, led to a late rc6 fix being required. In order to avoid this in the future we should document some expectations around linux-firmware.

I was originally going to write this for drm, but it seems quite generic advice.

I'm cc'ing this quite widely to reach subsystems which use fw a lot.

---
 Documentation/driver-api/firmware/core.rst    |  1 +
 .../firmware/firmware-usage-guidelines.rst    | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 Documentation/driver-api/firmware/firmware-usage-guidelines.rst
Documentation/driver-api/firmware/core.rst +1 -0
index 1d1688cbc078..803cd574bbd7 100644
@@ -13,4 +13,5 @@ documents these features.
    direct-fs-lookup
    fallback-mechanisms
    lookup-order
+   firmware-usage-guidelines
 
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +34 -0
new file mode 100644
index 000000000000..34d2412e78c6
@@ -0,0 +1,34 @@
+===================
+Firmware Guidelines
+===================
+
+Drivers that use firmware from linux-firmware should attempt to follow
+the rules in this guide.
+
+* Firmware should be versioned with at least a major/minor version. It
+  is suggested that the firmware files in linux-firmware be named with
+  some device specific name, and just the major version. The
+  major/minor/patch versions should be stored in a header in the
+  firmware file for the driver to detect any non-ABI fixes/issues. The
+  firmware files in linux-firmware should be overwritten with the newest
+  compatible major version. Newer major version firmware should remain
+  compatible with all kernels that load that major number.
+
+* Users should *not* have to install newer firmware to use existing
+  hardware when they install a newer kernel.  If the hardware isn't
+  enabled by default or under development, this can be ignored, until
+  the first kernel release that enables that hardware.  This means no
+  major version bumps without the kernel retaining backwards
+  compatibility for the older major versions.  Minor version bumps
+  should not introduce new features that newer kernels depend on
+  non-optionally.
+
+* If a security fix needs lockstep firmware and kernel fixes in order to
+  be successful, then all supported major versions in the linux-firmware
+  repo should be updated with the security fix, and the kernel patches
+  should detect if the firmware is new enough to declare if the security
+  issue is fixed.  All communications around security fixes should point
+  at both the firmware and kernel fixes. If a security fix requires
+  deprecating old major versions, then this should only be done as a
+  last option, and be stated clearly in all communications.
+
Signature · 1 line
2.36.1
#1 lore raw
Quoted 11 lines · Dave Airlie

From: Dave Airlie <[email protected]>

A recent snafu where Intel ignored upstream feedback on a firmware change, led to a late rc6 fix being required. In order to avoid this in the future we should document some expectations around linux-firmware.

I was originally going to write this for drm, but it seems quite generic advice.

I'm cc'ing this quite widely to reach subsystems which use fw a lot.

Thx for this, I kinda put "add a few words about firmware into Documentation/process/handling-regressions.rst" on my todo list already, but having a separate document is likely better.

Took a quick look, here are a few suggestions for your consideration.

Documentation/driver-api/firmware/firmware-usage-guidelines.rst line 6

Quoted 13 lines

[...]

Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +6 -0
new file mode 100644
index 000000000000..34d2412e78c6
@@ -0,0 +1,34 @@
+===================
+Firmware Guidelines
+===================
+
+Drivers that use firmware from linux-firmware should attempt to follow
+the rules in this guide.

How about spelling out the main aspect first clearly before going into the details about its consequence? Maybe something along these lines:

```
Users switching to a newer kernel should *not* have to install newer
firmware files to keep their hardware working. At the same time updated
firmware files must not cause any regressions for users of older kernel
releases.

Drivers that use such firmware (like that in linux-firmware) should thus
follow these rules:
```

Documentation/driver-api/firmware/firmware-usage-guidelines.rst

Quoted 11 lines
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +11 -0
+* Firmware should be versioned with at least a major/minor version it
+  is suggested that the firmware files in linux-firmware be named with
+  some device specific name, and just the major version. The
+  major/minor/patch versions should be stored in a header in the
+  firmware file for the driver to detect any non-ABI fixes/issues. The
+  firmware files in linux-firmware should be overwritten with the newest
+  compatible major version. Newer major version firmware should remain
+  compatible with all kernels that load that major number.
+
+* Users should *not* have to install newer firmware to use existing
+  hardware when they install a newer kernel. 

This will need changes if you pick up the suggestion above.

Quoted 2 lines

If the hardware isn't
+ enabled by default or under development,

Wondering if it might be better to drop the "or under development", as the "enabled by default" is the main part afaics. Maybe something like "If support for the hardware is normally inactive (e.g. has to be enabled manually by a kernel parameter)" would be better anyway.

Documentation/driver-api/firmware/firmware-usage-guidelines.rst

Quoted 10 lines

this can be ignored, until

Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +9 -0
+  the first kernel release that enables that hardware.  This means no
+  major version bumps without the kernel retaining backwards
+  compatibility for the older major versions.  Minor version bumps
+  should not introduce new features that newer kernels depend on
+  non-optionally.
+
+* If a security fix needs lockstep firmware and kernel fixes in order to
+  be successful, then all supported major versions in the linux-firmware
+  repo

This made me wonder: what exactly are "all supported major versions" in this context? Do you mean something like "all major versions in the linux-firmware required by currently supported stable/longterm kernel series"? Then it might be wise to write that.

Documentation/driver-api/firmware/firmware-usage-guidelines.rst line 34

Quoted 7 lines

should be updated with the security fix, and the kernel patches

Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +6 -0
+  should detect if the firmware is new enough to declare if the security
+  issue is fixed.  All communications around security fixes should point
+  at both the firmware and kernel fixes. If a security fix requires
+  deprecating old major versions, then this should only be done as a
+  last option, and be stated clearly in all communications.
+

HTH, Ciao, Thorsten

Acked-by on v1 1/1
#4 lore raw
In reply to Dave Airlie
Quoted 40 lines · Dave Airlie

From: Dave Airlie <[email protected]>

A recent snafu where Intel ignored upstream feedback on a firmware change, led to a late rc6 fix being required. In order to avoid this in the future we should document some expectations around linux-firmware.

I was originally going to write this for drm, but it seems quite generic advice.

I'm cc'ing this quite widely to reach subsystems which use fw a lot.

---
 Documentation/driver-api/firmware/core.rst    |  1 +
 .../firmware/firmware-usage-guidelines.rst    | 34 +++++++++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 Documentation/driver-api/firmware/firmware-usage-guidelines.rst
Documentation/driver-api/firmware/core.rst +1 -0
index 1d1688cbc078..803cd574bbd7 100644
@@ -13,4 +13,5 @@ documents these features.
    direct-fs-lookup
    fallback-mechanisms
    lookup-order
+   firmware-usage-guidelines
 
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +5 -0
new file mode 100644
index 000000000000..34d2412e78c6
@@ -0,0 +1,34 @@
+===================
+Firmware Guidelines
+===================
+
+Drivers that use firmware from linux-firmware should attempt to follow

Documentation/driver-api/firmware/firmware-usage-guidelines.rst line 15

Quoted 10 lines
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +10 -0
+the rules in this guide.
+
+* Firmware should be versioned with at least a major/minor version. It
+  is suggested that the firmware files in linux-firmware be named with
+  some device specific name, and just the major version. The
+  major/minor/patch versions should be stored in a header in the
+  firmware file for the driver to detect any non-ABI fixes/issues. The
+  firmware files in linux-firmware should be overwritten with the newest
+  compatible major version. Newer major version firmware should remain
+  compatible with all kernels that load that major number.

would symbolic links be acceptable in the linux-firmware.git where the <fmw>_<major>.bin is a sym link to <fwm>_<major>.<minor>.bin

or having the <fwm>_<major>.bin really to be the overwritten every minor update?

Quoted 8 lines
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +8 -0
+
+* Users should *not* have to install newer firmware to use existing
+  hardware when they install a newer kernel.  If the hardware isn't
+  enabled by default or under development, this can be ignored, until
+  the first kernel release that enables that hardware.  This means no
+  major version bumps without the kernel retaining backwards
+  compatibility for the older major versions.  Minor version bumps
+  should not introduce new features that newer kernels depend on

Documentation/driver-api/firmware/firmware-usage-guidelines.rst line 33

Quoted 10 lines
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +10 -0
+  non-optionally.
+
+* If a security fix needs lockstep firmware and kernel fixes in order to
+  be successful, then all supported major versions in the linux-firmware
+  repo should be updated with the security fix, and the kernel patches
+  should detect if the firmware is new enough to declare if the security
+  issue is fixed.  All communications around security fixes should point
+  at both the firmware and kernel fixes. If a security fix requires
+  deprecating old major versions, then this should only be done as a
+  last option, and be stated clearly in all communications.

Everything makes sense to me. Thanks for writing this down.

Quoted 11 lines
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +1 -0
+
Signature · 9 lines
2.36.1



--
_______________________________________________
Dri-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/dri-devel
Acked-by on v1 1/1
#7 lore raw
In reply to Dave Airlie
Quoted 7 lines · Dave Airlie

From: Dave Airlie <[email protected]>

A recent snafu where Intel ignored upstream feedback on a firmware change, led to a late rc6 fix being required. In order to avoid this in the future we should document some expectations around linux-firmware.

Quoted 6 lines

I was originally going to write this for drm, but it seems quite generic advice.

I'm cc'ing this quite widely to reach subsystems which use fw a lot.

Document well deserved to be written, thanks for making this happen. Modulo all the silly spelling / bike-shedding issues folks might find, in case you care to re-spin for a v2:

Now let's think about the impact of two corner cases which *do* happen and so this poses security implications on enablement:

1) Devices which end up with a security issue which a vendor considers obsolete, and the only way to fix something is firmware. We're security-out-of-luck. For this I've previously sucessfully have put effort into organizations to open source the firmware. We were successful more than once:

* https://github.com/qca/open-ath9k-htc-firmware
* https://github.com/qca/ath6kl-firmware

When these efforts fall short we have a slew of reverse engineering efforts which fortunately also have been sucessfull.

2) Vendor goes belly up

Both implicate the need to help persuade early on a strategy for open source firmware, and I don't want to hear anyone tell me it is not possible.

When that fails we can either reverse engineer and worst case, I am not sure if we have a process for annotations or should. Perhaps a kconfig symbol which drivers with buggy firmware can depend on, and only if you enable that kconfig symbol would these drivers be available to be enabled?

Are we aware of such device drivers? They must exist...

Luis

maintainer
#2 lore raw
In reply to Thorsten Leemhuis
Quoted 7 lines · On Mon, 18 Jul 2022 11:33:11 +0200 Thorsten Leemhuis wrote:
Quoted 2 lines

If the hardware isn't
+ enabled by default or under development,

Wondering if it might be better to drop the "or under development", as the "enabled by default" is the main part afaics. Maybe something like "If support for the hardware is normally inactive (e.g. has to be enabled manually by a kernel parameter)" would be better anyway.

It's a tricky one, I'd say something like you can break the FW ABI "until HW becomes available for public consumption" or such. I'm guessing what we're after is letting people break the compatibility in early stages of the product development cycles. Pre-silicon and bring up, but not after there are products on the market?

#5 lore raw
In reply to Rodrigo Vivi
Quoted 9 lines

Documentation/driver-api/firmware/firmware-usage-guidelines.rst line 15

Quoted 8 lines
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +8 -0
+* Firmware should be versioned with at least a major/minor version. It
+  is suggested that the firmware files in linux-firmware be named with
+  some device specific name, and just the major version. The
+  major/minor/patch versions should be stored in a header in the
+  firmware file for the driver to detect any non-ABI fixes/issues. The
+  firmware files in linux-firmware should be overwritten with the newest
+  compatible major version. Newer major version firmware should remain
+  compatible with all kernels that load that major number.
Quoted 5 lines

would symbolic links be acceptable in the linux-firmware.git where the <fmw>_<major>.bin is a sym link to <fwm>_<major>.<minor>.bin

or having the <fwm>_<major>.bin really to be the overwritten every minor update?

I don't think providing multiple minor versions of fw in linux-firmware is that interesting.
Like if the major is the same, surely you always want the newer ones. As long as the
ABI doesn't break. Otherwise we are just wasting disk space with fws nobody will be using.

Dave.

#3 lore raw
In reply to Jakub Kicinski
Quoted 10 lines · Jakub Kicinski
Quoted 7 lines · On Mon, 18 Jul 2022 11:33:11 +0200 Thorsten Leemhuis wrote:
Quoted 2 lines

If the hardware isn't
+ enabled by default or under development,

Wondering if it might be better to drop the "or under development", as the "enabled by default" is the main part afaics. Maybe something like "If support for the hardware is normally inactive (e.g. has to be enabled manually by a kernel parameter)" would be better anyway.

Quoted 5 lines

It's a tricky one, I'd say something like you can break the FW ABI "until HW becomes available for public consumption" or such. I'm guessing what we're after is letting people break the compatibility in early stages of the product development cycles. Pre-silicon and bring up, but not after there are products on the market?

I'll stick with enabled by default I think, "public consumption" invites efforts to describe corners of the cloud or other places where hw has shipped but is not technically "public",

Dave.

#6 lore raw
In reply to Dave Airlie
Quoted 15 lines · Dave Airlie
Quoted 9 lines

Documentation/driver-api/firmware/firmware-usage-guidelines.rst line 15

Quoted 8 lines
Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file +8 -0
+* Firmware should be versioned with at least a major/minor version. It
+  is suggested that the firmware files in linux-firmware be named with
+  some device specific name, and just the major version. The
+  major/minor/patch versions should be stored in a header in the
+  firmware file for the driver to detect any non-ABI fixes/issues. The
+  firmware files in linux-firmware should be overwritten with the newest
+  compatible major version. Newer major version firmware should remain
+  compatible with all kernels that load that major number.
Quoted 5 lines

would symbolic links be acceptable in the linux-firmware.git where the <fmw>_<major>.bin is a sym link to <fwm>_<major>.<minor>.bin

or having the <fwm>_<major>.bin really to be the overwritten every minor update?

Quoted 6 lines

I don't think providing multiple minor versions of fw in linux-firmware is that interesting.
Like if the major is the same, surely you always want the newer ones. As long as the
ABI doesn't break. Otherwise we are just wasting disk space with fws nobody will be using.

It was my understanding that once a firmware file is in linux-firmware it's there forever. There are tons of existing symlinks to point to the latest version, but the previous versions are not removed/overwritten.

see random examples:
ls -lR /lib/firmware | grep t4fw
ls -lR /lib/firmware | grep fw_release