tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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>

authored by

Dave Airlie and committed by
Greg Kroah-Hartman 321eaf31 3fcbf1c7

+45
+1
Documentation/driver-api/firmware/core.rst
··· 13 13 direct-fs-lookup 14 14 fallback-mechanisms 15 15 lookup-order 16 + firmware-usage-guidelines 16 17
+44
Documentation/driver-api/firmware/firmware-usage-guidelines.rst
··· 1 + =================== 2 + Firmware Guidelines 3 + =================== 4 + 5 + Users switching to a newer kernel should *not* have to install newer 6 + firmware files to keep their hardware working. At the same time updated 7 + firmware files must not cause any regressions for users of older kernel 8 + releases. 9 + 10 + Drivers that use firmware from linux-firmware should follow the rules in 11 + this guide. (Where there is limited control of the firmware, 12 + i.e. company doesn't support Linux, firmwares sourced from misc places, 13 + then of course these rules will not apply strictly.) 14 + 15 + * Firmware files shall be designed in a way that it allows checking for 16 + firmware ABI version changes. It is recommended that firmware files be 17 + versioned with at least a major/minor version. It is suggested that 18 + the firmware files in linux-firmware be named with some device 19 + specific name, and just the major version. The firmware version should 20 + be stored in the firmware header, or as an exception, as part of the 21 + firmware file name, in order to let the driver detact any non-ABI 22 + fixes/changes. The firmware files in linux-firmware should be 23 + overwritten with the newest compatible major version. Newer major 24 + version firmware shall remain compatible with all kernels that load 25 + that major number. 26 + 27 + * If the kernel support for the hardware is normally inactive, or the 28 + hardware isn't available for public consumption, this can 29 + be ignored, until the first kernel release that enables that hardware. 30 + This means no major version bumps without the kernel retaining 31 + backwards compatibility for the older major versions. Minor version 32 + bumps should not introduce new features that newer kernels depend on 33 + non-optionally. 34 + 35 + * If a security fix needs lockstep firmware and kernel fixes in order to 36 + be successful, then all supported major versions in the linux-firmware 37 + repo that are required by currently supported stable/LTS kernels, 38 + should be updated with the security fix. The kernel patches should 39 + detect if the firmware is new enough to declare if the security issue 40 + is fixed. All communications around security fixes should point at 41 + both the firmware and kernel fixes. If a security fix requires 42 + deprecating old major versions, then this should only be done as a 43 + last option, and be stated clearly in all communications. 44 +