On 2022-07-19 02:53, Dave Airlie wrote: > From: Dave Airlie <airlied@xxxxxxxxxx> > > 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. > > v2: rewritten with suggestions from Thorsten Leemhuis. > > Acked-by: Luis Chamberlain <mcgrof@xxxxxxxxxx> > Acked-by: Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx> Acked-by: Harry Wentland <harry.wentland@xxxxxxx> Harry > Signed-off-by: Dave Airlie <airlied@xxxxxxxxxx> > --- > 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 > > 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. > +
