0001 ===================
0002 Firmware Guidelines
0003 ===================
0004
0005 Users switching to a newer kernel should *not* have to install newer
0006 firmware files to keep their hardware working. At the same time updated
0007 firmware files must not cause any regressions for users of older kernel
0008 releases.
0009
0010 Drivers that use firmware from linux-firmware should follow the rules in
0011 this guide. (Where there is limited control of the firmware,
0012 i.e. company doesn't support Linux, firmwares sourced from misc places,
0013 then of course these rules will not apply strictly.)
0014
0015 * Firmware files shall be designed in a way that it allows checking for
0016 firmware ABI version changes. It is recommended that firmware files be
0017 versioned with at least a major/minor version. It is suggested that
0018 the firmware files in linux-firmware be named with some device
0019 specific name, and just the major version. The firmware version should
0020 be stored in the firmware header, or as an exception, as part of the
0021 firmware file name, in order to let the driver detact any non-ABI
0022 fixes/changes. The firmware files in linux-firmware should be
0023 overwritten with the newest compatible major version. Newer major
0024 version firmware shall remain compatible with all kernels that load
0025 that major number.
0026
0027 * If the kernel support for the hardware is normally inactive, or the
0028 hardware isn't available for public consumption, this can
0029 be ignored, until the first kernel release that enables that hardware.
0030 This means no major version bumps without the kernel retaining
0031 backwards compatibility for the older major versions. Minor version
0032 bumps should not introduce new features that newer kernels depend on
0033 non-optionally.
0034
0035 * If a security fix needs lockstep firmware and kernel fixes in order to
0036 be successful, then all supported major versions in the linux-firmware
0037 repo that are required by currently supported stable/LTS kernels,
0038 should be updated with the security fix. The kernel patches should
0039 detect if the firmware is new enough to declare if the security issue
0040 is fixed. All communications around security fixes should point at
0041 both the firmware and kernel fixes. If a security fix requires
0042 deprecating old major versions, then this should only be done as a
0043 last option, and be stated clearly in all communications.
0044
