| Message ID | 20220718072144.2699487-1-airlied@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs: driver-api: firmware: add driver firmware guidelines. | expand |
> > +* 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? 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. --
On Tue, 19 Jul 2022 at 08:04, Jakub Kicinski <kuba@kernel.org> wrote: > > On Mon, 18 Jul 2022 11:33:11 +0200 Thorsten Leemhuis wrote: > > > 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? 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. --
diff --git a/Documentation/driver-api/firmware/core.rst b/Documentation/driver-api/firmware/core.rst index 1d1688cbc078..803cd574bbd7 100644 --- a/Documentation/driver-api/firmware/core.rst +++ b/Documentation/driver-api/firmware/core.rst @@ -13,4 +13,5 @@ documents these features. direct-fs-lookup fallback-mechanisms lookup-order + firmware-usage-guidelines diff --git a/Documentation/driver-api/firmware/firmware-usage-guidelines.rst b/Documentation/driver-api/firmware/firmware-usage-guidelines.rst new file mode 100644 index 000000000000..34d2412e78c6 --- /dev/null +++ b/Documentation/driver-api/firmware/firmware-usage-guidelines.rst @@ -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. +