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