Re: [PATCH] docs: driver-api: firmware: add driver firmware guidelines. (v2)

Harry Wentland
2022-07-19T14:35:24Z

On 2022-07-19 02:53, Dave Airlie wrote:
> From: Dave Airlie <airlied@redhat.com>
>
> 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.
>
> Acked-by: Luis Chamberlain <mcgrof@kernel.org>
> Acked-by: Rodrigo Vivi <rodrigo.vivi@intel.com>

Acked-by: Harry Wentland <harry.wentland@amd.com>

Harry

> Signed-off-by: Dave Airlie <airlied@redhat.com>
> ---
> Documentation/driver-api/firmware/core.rst | 1 +
> .../firmware/firmware-usage-guidelines.rst | 34 +++++++++++++++++++
> 2 files changed, 35 insertions(+)
> create mode 100644 Documentation/driver-api/firmware/firmware-usage-guidelines.rst
>
> diff --git a/Documentation/driver-api/firmware/core.rst b/Documentation/driver-api/firmware/core.rst
> index 1d1688cbc078..803cd574bbd7 100644
> --- a/Documentation/driver-api/firmware/core.rst
> +++ b/Documentation/driver-api/firmware/core.rst
> @@ -13,4 +13,5 @@ documents these features.
> direct-fs-lookup
> fallback-mechanisms
> lookup-order
> + firmware-usage-guidelines
>
> diff --git a/Documentation/driver-api/firmware/firmware-usage-guidelines.rst b/Documentation/driver-api/firmware/firmware-usage-guidelines.rst
> new file mode 100644
> index 000000000000..34d2412e78c6
> --- /dev/null
> +++ b/Documentation/driver-api/firmware/firmware-usage-guidelines.rst
> @@ -0,0 +1,34 @@
> +===================
> +Firmware Guidelines
> +===================
> +
> +Drivers that use firmware from linux-firmware should attempt to follow
> +the rules in this guide.
> +
> +* Firmware should be versioned with at least a major/minor version. It
> + is suggested that the firmware files in linux-firmware be named with
> + some device specific name, and just the major version. The
> + major/minor/patch versions should be stored in a header in the
> + firmware file for the driver to detect any non-ABI fixes/issues. The
> + firmware files in linux-firmware should be overwritten with the newest
> + compatible major version. Newer major version firmware should remain
> + compatible with all kernels that load that major number.
> +
> +* Users should *not* have to install newer firmware to use existing
> + hardware when they install a newer kernel. If the hardware isn't
> + enabled by default or under development, this can be ignored, until
> + the first kernel release that enables that hardware. This means no
> + major version bumps without the kernel retaining backwards
> + compatibility for the older major versions. Minor version bumps
> + should not introduce new features that newer kernels depend on
> + non-optionally.
> +
> +* If a security fix needs lockstep firmware and kernel fixes in order to
> + be successful, then all supported major versions in the linux-firmware
> + repo should be updated with the security fix, and the kernel patches
> + should detect if the firmware is new enough to declare if the security
> + issue is fixed. All communications around security fixes should point
> + at both the firmware and kernel fixes. If a security fix requires
> + deprecating old major versions, then this should only be done as a
> + last option, and be stated clearly in all communications.
> +