mirrors
/
linux-stable
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
1
0
Fork 0
Code Issues Releases Wiki Activity

docs: driver-api: firmware: add driver firmware guidelines. (v3) 

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
v3: rewritten with suggestions from Mauro

Acked-by: Luis Chamberlain <mcgrof@kernel.org>
Acked-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Acked-by: Daniel Vetter <daniel@ffwll.ch>
Acked-by: Harry Wentland <harry.wentland@amd.com>
Signed-off-by: Dave Airlie <airlied@redhat.com>
Link: https://lore.kernel.org/r/20220721044352.3110507-1-airlied@gmail.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Dave Airlie 2022-07-21 14:43:52 +10:00 committed by Greg Kroah-Hartman
parent 3fcbf1c77d
commit 321eaf317d
2 changed files with 45 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/driver-api/firmware/core.rst
View File

@ -13,4 +13,5 @@ documents these features.
direct-fs-lookup
fallback-mechanisms
lookup-order
firmware-usage-guidelines

44
Documentation/driver-api/firmware/firmware-usage-guidelines.rst Normal file
View File

@ -0,0 +1,44 @@
===================
Firmware Guidelines
===================
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 firmware from linux-firmware should follow the rules in
this guide. (Where there is limited control of the firmware,
i.e. company doesn't support Linux, firmwares sourced from misc places,
then of course these rules will not apply strictly.)
* Firmware files shall be designed in a way that it allows checking for
firmware ABI version changes. It is recommended that firmware files 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 firmware version should
be stored in the firmware header, or as an exception, as part of the
firmware file name, in order to let the driver detact any non-ABI
fixes/changes. The firmware files in linux-firmware should be
overwritten with the newest compatible major version. Newer major
version firmware shall remain compatible with all kernels that load
that major number.
* If the kernel support for the hardware is normally inactive, or the
hardware isn't available for public consumption, 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 that are required by currently supported stable/LTS kernels,
should be updated with the security fix. 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.