driver-api/firmware/fallback-mechanisms.rst

6 filesystem lookup on the root filesystem or when the firmware simply cannot be
8 configuration options related to supporting the firmware fallback mechanism are:
10   * CONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback
15     enable the kobject uevent fallback mechanism on all firmware API calls
21     manually load the firmware. Read below for more details.
31 Justifying the firmware fallback mechanism
40 * Races upon resume from suspend. This is resolved by the firmware cache, but
41   the firmware cache is only supported if you use uevents, and its not
44 * Firmware is not accessible through typical means:
47         * The firmware provides very unique device specific data tailored for
65 Firmware sysfs loading facility
68 In order to help device drivers upload firmware using a fallback mechanism
69 the firmware infrastructure creates a sysfs interface to enable userspace
70 to load and indicate when firmware is ready. The sysfs directory is created
72 the firmware requested, and establishes it in the device hierarchy by
76 This is actually where the original firmware_class module name came from,
77 given that originally the only firmware loading mechanism available was the
79 firmware_class. Because the attributes exposed are part of the module name, the
80 module name firmware_class cannot be renamed in the future, to ensure backward
83 To load firmware using the sysfs interface we expose a loading indicator,
84 and a file upload firmware into:
89 To upload firmware you will echo 1 onto the loading file to indicate
90 you are loading firmware. You then write the firmware into the data file,
91 and you notify the kernel the firmware is ready by echo'ing 0 onto
94 The firmware device used to help load firmware using sysfs is only created if
95 direct firmware loading fails and if the fallback mechanism is enabled for your
96 firmware request, this is set up with :c:func:`firmware_fallback_sysfs`. It is
97 important to re-iterate that no device is created if a direct filesystem lookup
104 Will clean any previous partial load at once and make the firmware API
105 return an error. When loading firmware the firmware_class grows a buffer
106 for the firmware in PAGE_SIZE increments to hold the image as it comes in.
113 -----------------------
114 .. kernel-doc:: drivers/base/firmware_loader/fallback.c
117 Firmware kobject uevent fallback mechanism
120 Since a device is created for the sysfs interface to help load firmware as a
123 hierarchy means the fallback mechanism for firmware loading has been initiated.
137 this fallback mechanism. When firmware loading was only possible using the
140 udev, however firmware loading support was removed from udev as of systemd
141 commit be2ea723b1d0 ("udev: remove userspace firmware loading support")
143 not using or taking advantage of the firmware fallback mechanism provided
151 * FIRMWARE=firmware name
158         # Both $DEVPATH and $FIRMWARE are already provided in the environment.
159         MY_FW_DIR=/lib/firmware/
161         cat $MY_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data
164 Firmware custom fallback mechanism
170 was that utilities other than udev might be required to lookup firmware
171 in non-traditional paths -- paths outside of the listing documented in the
179 also setup the firmware cache for firmware requests. As documented above,
180 the firmware cache is only set up if uevent is enabled for an API call.
181 Although this can disable the firmware cache for request_firmware_nowait()
184 the uevent flag means you want to opt-in for the firmware fallback mechanism
187 load firmware for you through a custom path.
189 Firmware fallback timeout
192 The firmware fallback mechanism has a timeout. If firmware is not loaded
196 The logic behind using MAX_JIFFY_OFFSET for non-uevents is that a custom
197 solution will have as much time as it needs to load firmware.
199 You can customize the firmware timeout by echo'ing your desired timeout into
202 * /sys/class/firmware/timeout
207 EFI embedded firmware fallback mechanism
211 of firmware for some of the system's integrated peripheral devices and
212 the peripheral's Linux device-driver needs to access this firmware.
214 Device drivers which need such firmware can use the
219 A device driver which needs this can describe the firmware it needs
222 .. kernel-doc:: include/linux/efi_embedded_fw.h
225 The EFI embedded-fw code works by scanning all EFI_BOOT_SERVICES_CODE memory
234 To register this array with the efi-embedded-fw code, a driver needs to:
243    drivers/firmware/efi/embedded-firmware.c wrapped in a #ifdef testing that
248 The firmware_request_platform() function will always first try to load firmware
249 with the specified name directly from the disk, so the EFI embedded-fw can
250 always be overridden by placing a file under /lib/firmware.
254 1. The code scanning for EFI embedded-firmware runs near the end
258    embedded-firmware.
260 2. At the moment the EFI embedded-fw code assumes that firmwares always start at
264 3. At the moment the EFI embedded-fw code only works on x86 because other archs
265    free EFI_BOOT_SERVICES_CODE before the EFI embedded-fw code gets a chance to
268 4. The current brute-force scanning of EFI_BOOT_SERVICES_CODE is an ad-hoc
269    brute-force solution. There has been discussion to use the UEFI Platform
270    Initialization (PI) spec's Firmware Volume protocol. This has been rejected
272    1. The PI spec does not define peripheral firmware at all
278 Example how to check for and extract embedded firmware
279 ------------------------------------------------------
281 To check for, for example Silead touchscreen controller embedded firmware,
288 3. Open the boot_services_code? files in a hex-editor, search for the
289    magic prefix for Silead firmware: F0 00 00 00 02 00 00 00, this gives you
290    the beginning address of the firmware inside the boot_services_code? file.
292 4. The firmware has a specific pattern, it starts with a 8 byte page-address,
293    typically F0 00 00 00 02 00 00 00 for the first page followed by 32-bit
294    word-address + 32-bit value pairs. With the word-address incrementing 4
296    followed by a new page-address, followed by more word + value pairs. This
298    this gives you the end of the firmware inside the boot_services_code? file.
300 5. "dd if=boot_services_code? of=firmware bs=1 skip=<begin-addr> count=<len>"
301    will extract the firmware for you. Inspect the firmware file in a
304 6. Copy it to /lib/firmware under the expected name to test it.
306 7. If the extracted firmware works, you can use the found info to fill an
307    efi_embedded_fw_desc struct to describe it, run "sha256sum firmware"