From 0e41c1bcbdc8c1ab370b29b131bce7ea6814e1b2 Mon Sep 17 00:00:00 2001 From: Aelin Date: Wed, 4 Mar 2026 20:55:03 +0100 Subject: [PATCH] docs: Add documentation on firmware packaging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add firmware packaging guidelines to the documentation. The goal behind this was to make it so that it is very clear which packaging method is preferred for which cases to avoid fragmentation and inconsistency in pmaports packaging. Co-authored-by: Pablo Correa Gómez Part-of: --- docs/firmware.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + 2 files changed, 59 insertions(+) create mode 100644 docs/firmware.md diff --git a/docs/firmware.md b/docs/firmware.md new file mode 100644 index 000000000..1a788a711 --- /dev/null +++ b/docs/firmware.md @@ -0,0 +1,58 @@ +# Firmware + +Firmware (non-free binary blobs, often cryptographically signed by the OEM) +is nowadays unfortunately required for a lot of essential functionality, +especially on mobile devices with wireless connectivity or graphics processors. + +## User choice + +While for the longest time, pmbootstrap used to prompt the user whether they +wanted to install firmware or not, it was decided in early 2024 that nonfree +firmware would be [installed by +default](https://postmarketos.org/edge/2024/02/15/default-nonfree-fw/). + +Nonfree firmware dependencies should therefore now be in the `depends` of the +device package and also not in a separate subpackage. It would technically be +possible to put it in `_pmb_recommends` as well to allow users to uninstall it +later, but that is not recommended for the reasons discussed in the blog post. +Maintainers will have an easier time troubleshooting bug reports if they do not +need to account for the possibility that the user may have uninstalled required +firmware dependencies. Any such setup should therefore be considered custom, +and not something maintainers will generally be able to help with. + +## Packaging + +There are three endorsed methods for providing the nonfree firmware to the +kernel, in order of preference: + +1. Using firmware files already in `linux-firmware` upstream +2. Packaging them in pmaports, e.g. a `firmware-vendor-device` package +3. Reusing the firmware present on a partition on the device + +Firmware files in `linux-firmware` should be preferred if possible and not +repackaged in pmaports, with exceptions possible to make the installed firmware +more granular. This is for example done for the Qualcomm Adreno GPU firmware in +pmaports, which is packaged as `firmware-qcom-adreno-*` and allows device +packages to depend on their GPU firmware without pulling in the entirety of +`linux-firmware-qcom`. Similar such packages may be added in the future and +should be preferred over the larger packages where possible. + +When that is not possible, for example because the vendors did not send the +firmware upstream, it is recommended to package the firmware files directly in +pmaports. It prevents potential race conditions between services and greatly +simplifies the setup, making it easier to reason about what is going on in the +system. It is also generally considered the most secure alternative. CVEs in +non-free firmware for things like the modem have existed. Packaging firmware and +keeping it up-to-date ensures that all users get the newest security patches, +and do not depend on the Android version they had before installing +postmarketOS. + +Unfortunately, there are cases where none of the other options are possible, for +example, when firmware files are specific to the device: unit-specific +calibration data, region-specific WiFi or modem firmware files, etc. In those +cases it is reasonable to load the firmware from e.g. the Android partition +with those files. This can be done using +[msm-firmware-loader](https://gitlab.postmarketos.org/postmarketOS/msm-firmware-loader), +which, despite the name, can be modified to suit other devices than just +Qualcomm-based ones. Extremely space-constrained devices may also use this +approach if required. diff --git a/docs/index.md b/docs/index.md index 4f92047dc..e7687196e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,6 +17,7 @@ in pmaports and the processes around device categorization. device-categorization deviceinfo-reference ci-tags + firmware generic-device-packages generic-kernels kconfig-fragments