| 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 |
|
| 45 |
* Firmware files that affect the User API (UAPI) shall not introduce |
| 46 |
changes that break existing userspace programs. Updates to such firmware |
| 47 |
must ensure backward compatibility with existing userspace applications. |
| 48 |
This includes maintaining consistent interfaces and behaviors that |
| 49 |
userspace programs rely on. |