1===================
 2Firmware Guidelines
 3===================
 4
 5Users switching to a newer kernel should *not* have to install newer
 6firmware files to keep their hardware working. At the same time updated
 7firmware files must not cause any regressions for users of older kernel
 8releases.
 9
10Drivers that use firmware from linux-firmware should follow the rules in
11this guide. (Where there is limited control of the firmware,
12i.e. company doesn't support Linux, firmwares sourced from misc places,
13then 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