^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Fallback mechanisms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) A fallback mechanism is supported to allow to overcome failures to do a direct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) filesystem lookup on the root filesystem or when the firmware simply cannot be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) installed for practical reasons on the root filesystem. The kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) configuration options related to supporting the firmware fallback mechanism are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) * CONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) mechanism. Most distributions enable this option today. If enabled but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) CONFIG_FW_LOADER_USER_HELPER_FALLBACK is disabled, only the custom fallback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) mechanism is available and for the request_firmware_nowait() call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) * CONFIG_FW_LOADER_USER_HELPER_FALLBACK: force enables each request to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) enable the kobject uevent fallback mechanism on all firmware API calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) except request_firmware_direct(). Most distributions disable this option
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) today. The call request_firmware_nowait() allows for one alternative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) fallback mechanism: if this kconfig option is enabled and your second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) argument to request_firmware_nowait(), uevent, is set to false you are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) informing the kernel that you have a custom fallback mechanism and it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) manually load the firmware. Read below for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Note that this means when having this configuration:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) CONFIG_FW_LOADER_USER_HELPER=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) CONFIG_FW_LOADER_USER_HELPER_FALLBACK=n
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) the kobject uevent fallback mechanism will never take effect even
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) for request_firmware_nowait() when uevent is set to true.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Justifying the firmware fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ==========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Direct filesystem lookups may fail for a variety of reasons. Known reasons for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) this are worth itemizing and documenting as it justifies the need for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) fallback mechanism:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) * Race against access with the root filesystem upon bootup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) * Races upon resume from suspend. This is resolved by the firmware cache, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) the firmware cache is only supported if you use uevents, and its not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) supported for request_firmware_into_buf().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) * Firmware is not accessible through typical means:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) * It cannot be installed into the root filesystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) * The firmware provides very unique device specific data tailored for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) the unit gathered with local information. An example is calibration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) data for WiFi chipsets for mobile devices. This calibration data is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) not common to all units, but tailored per unit. Such information may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) be installed on a separate flash partition other than where the root
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) filesystem is provided.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Types of fallback mechanisms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) There are really two fallback mechanisms available using one shared sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) interface as a loading facility:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) * Kobject uevent fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) * Custom fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) First lets document the shared sysfs loading facility.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Firmware sysfs loading facility
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) In order to help device drivers upload firmware using a fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) the firmware infrastructure creates a sysfs interface to enable userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) to load and indicate when firmware is ready. The sysfs directory is created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) via fw_create_instance(). This call creates a new struct device named after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) the firmware requested, and establishes it in the device hierarchy by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) associating the device used to make the request as the device's parent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) The sysfs directory's file attributes are defined and controlled through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) the new device's class (firmware_class) and group (fw_dev_attr_groups).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) This is actually where the original firmware_class module name came from,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) given that originally the only firmware loading mechanism available was the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) mechanism we now use as a fallback mechanism, which registers a struct class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) firmware_class. Because the attributes exposed are part of the module name, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) module name firmware_class cannot be renamed in the future, to ensure backward
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) compatibility with old userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) To load firmware using the sysfs interface we expose a loading indicator,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) and a file upload firmware into:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) * /sys/$DEVPATH/loading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) * /sys/$DEVPATH/data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) To upload firmware you will echo 1 onto the loading file to indicate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) you are loading firmware. You then write the firmware into the data file,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) and you notify the kernel the firmware is ready by echo'ing 0 onto
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) the loading file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) The firmware device used to help load firmware using sysfs is only created if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) direct firmware loading fails and if the fallback mechanism is enabled for your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) firmware request, this is set up with :c:func:`firmware_fallback_sysfs`. It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) important to re-iterate that no device is created if a direct filesystem lookup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) succeeded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Using::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) echo 1 > /sys/$DEVPATH/loading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) Will clean any previous partial load at once and make the firmware API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) return an error. When loading firmware the firmware_class grows a buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) for the firmware in PAGE_SIZE increments to hold the image as it comes in.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) firmware_data_read() and firmware_loading_show() are just provided for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) test_firmware driver for testing, they are not called in normal use or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) expected to be used regularly by userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) firmware_fallback_sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) .. kernel-doc:: drivers/base/firmware_loader/fallback.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) :functions: firmware_fallback_sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Firmware kobject uevent fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) ==========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Since a device is created for the sysfs interface to help load firmware as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) fallback mechanism userspace can be informed of the addition of the device by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) relying on kobject uevents. The addition of the device into the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) hierarchy means the fallback mechanism for firmware loading has been initiated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) For details of implementation refer to fw_load_sysfs_fallback(), in particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) on the use of dev_set_uevent_suppress() and kobject_uevent().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) The kernel's kobject uevent mechanism is implemented in lib/kobject_uevent.c,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) it issues uevents to userspace. As a supplement to kobject uevents Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) distributions could also enable CONFIG_UEVENT_HELPER_PATH, which makes use of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) core kernel's usermode helper (UMH) functionality to call out to a userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) helper for kobject uevents. In practice though no standard distribution has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) ever used the CONFIG_UEVENT_HELPER_PATH. If CONFIG_UEVENT_HELPER_PATH is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) enabled this binary would be called each time kobject_uevent_env() gets called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) in the kernel for each kobject uevent triggered.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) Different implementations have been supported in userspace to take advantage of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) this fallback mechanism. When firmware loading was only possible using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) sysfs mechanism the userspace component "hotplug" provided the functionality of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) monitoring for kobject events. Historically this was superseded be systemd's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) udev, however firmware loading support was removed from udev as of systemd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) commit be2ea723b1d0 ("udev: remove userspace firmware loading support")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) as of v217 on August, 2014. This means most Linux distributions today are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) not using or taking advantage of the firmware fallback mechanism provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) by kobject uevents. This is specially exacerbated due to the fact that most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) distributions today disable CONFIG_FW_LOADER_USER_HELPER_FALLBACK.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) Refer to do_firmware_uevent() for details of the kobject event variables
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) setup. The variables currently passed to userspace with a "kobject add"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) event are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) * FIRMWARE=firmware name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) * TIMEOUT=timeout value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) * ASYNC=whether or not the API request was asynchronous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) By default DEVPATH is set by the internal kernel kobject infrastructure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) Below is an example simple kobject uevent script::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) # Both $DEVPATH and $FIRMWARE are already provided in the environment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) MY_FW_DIR=/lib/firmware/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) echo 1 > /sys/$DEVPATH/loading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) cat $MY_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) echo 0 > /sys/$DEVPATH/loading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Firmware custom fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) Users of the request_firmware_nowait() call have yet another option available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) at their disposal: rely on the sysfs fallback mechanism but request that no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) kobject uevents be issued to userspace. The original logic behind this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) was that utilities other than udev might be required to lookup firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) in non-traditional paths -- paths outside of the listing documented in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) section 'Direct filesystem lookup'. This option is not available to any of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) the other API calls as uevents are always forced for them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) Since uevents are only meaningful if the fallback mechanism is enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) in your kernel it would seem odd to enable uevents with kernels that do not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) have the fallback mechanism enabled in their kernels. Unfortunately we also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) rely on the uevent flag which can be disabled by request_firmware_nowait() to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) also setup the firmware cache for firmware requests. As documented above,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) the firmware cache is only set up if uevent is enabled for an API call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) Although this can disable the firmware cache for request_firmware_nowait()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) calls, users of this API should not use it for the purposes of disabling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) the cache as that was not the original purpose of the flag. Not setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) the uevent flag means you want to opt-in for the firmware fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) but you want to suppress kobject uevents, as you have a custom solution which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) will monitor for your device addition into the device hierarchy somehow and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) load firmware for you through a custom path.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Firmware fallback timeout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) The firmware fallback mechanism has a timeout. If firmware is not loaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) onto the sysfs interface by the timeout value an error is sent to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) driver. By default the timeout is set to 60 seconds if uevents are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) desirable, otherwise MAX_JIFFY_OFFSET is used (max timeout possible).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) The logic behind using MAX_JIFFY_OFFSET for non-uevents is that a custom
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) solution will have as much time as it needs to load firmware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) You can customize the firmware timeout by echo'ing your desired timeout into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) the following file:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) * /sys/class/firmware/timeout
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) If you echo 0 into it means MAX_JIFFY_OFFSET will be used. The data type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) for the timeout is an int.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) EFI embedded firmware fallback mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) ========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) On some devices the system's EFI code / ROM may contain an embedded copy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) of firmware for some of the system's integrated peripheral devices and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) the peripheral's Linux device-driver needs to access this firmware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) Device drivers which need such firmware can use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) firmware_request_platform() function for this, note that this is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) separate fallback mechanism from the other fallback mechanisms and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) this does not use the sysfs interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) A device driver which needs this can describe the firmware it needs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) using an efi_embedded_fw_desc struct:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) .. kernel-doc:: include/linux/efi_embedded_fw.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) :functions: efi_embedded_fw_desc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) The EFI embedded-fw code works by scanning all EFI_BOOT_SERVICES_CODE memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) segments for an eight byte sequence matching prefix; if the prefix is found it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) then does a sha256 over length bytes and if that matches makes a copy of length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) bytes and adds that to its list with found firmwares.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) To avoid doing this somewhat expensive scan on all systems, dmi matching is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) used. Drivers are expected to export a dmi_system_id array, with each entries'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) driver_data pointing to an efi_embedded_fw_desc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) To register this array with the efi-embedded-fw code, a driver needs to:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) 1. Always be builtin to the kernel or store the dmi_system_id array in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) separate object file which always gets builtin.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) 2. Add an extern declaration for the dmi_system_id array to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) include/linux/efi_embedded_fw.h.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 3. Add the dmi_system_id array to the embedded_fw_table in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) drivers/firmware/efi/embedded-firmware.c wrapped in a #ifdef testing that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) the driver is being builtin.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 4. Add "select EFI_EMBEDDED_FIRMWARE if EFI_STUB" to its Kconfig entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) The firmware_request_platform() function will always first try to load firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) with the specified name directly from the disk, so the EFI embedded-fw can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) always be overridden by placing a file under /lib/firmware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) Note that:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) 1. The code scanning for EFI embedded-firmware runs near the end
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) of start_kernel(), just before calling rest_init(). For normal drivers and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) subsystems using subsys_initcall() to register themselves this does not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) matter. This means that code running earlier cannot use EFI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) embedded-firmware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) 2. At the moment the EFI embedded-fw code assumes that firmwares always start at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) an offset which is a multiple of 8 bytes, if this is not true for your case
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) send in a patch to fix this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) 3. At the moment the EFI embedded-fw code only works on x86 because other archs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) free EFI_BOOT_SERVICES_CODE before the EFI embedded-fw code gets a chance to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) scan it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) 4. The current brute-force scanning of EFI_BOOT_SERVICES_CODE is an ad-hoc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) brute-force solution. There has been discussion to use the UEFI Platform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) Initialization (PI) spec's Firmware Volume protocol. This has been rejected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) because the FV Protocol relies on *internal* interfaces of the PI spec, and:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) 1. The PI spec does not define peripheral firmware at all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) 2. The internal interfaces of the PI spec do not guarantee any backward
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) compatibility. Any implementation details in FV may be subject to change,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) and may vary system to system. Supporting the FV Protocol would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) difficult as it is purposely ambiguous.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) Example how to check for and extract embedded firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) ------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) To check for, for example Silead touchscreen controller embedded firmware,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) do the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) 1. Boot the system with efi=debug on the kernel commandline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) 2. cp /sys/kernel/debug/efi/boot_services_code? to your home dir
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) 3. Open the boot_services_code? files in a hex-editor, search for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) magic prefix for Silead firmware: F0 00 00 00 02 00 00 00, this gives you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) the beginning address of the firmware inside the boot_services_code? file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) 4. The firmware has a specific pattern, it starts with a 8 byte page-address,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) typically F0 00 00 00 02 00 00 00 for the first page followed by 32-bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) word-address + 32-bit value pairs. With the word-address incrementing 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) bytes (1 word) for each pair until a page is complete. A complete page is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) followed by a new page-address, followed by more word + value pairs. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) leads to a very distinct pattern. Scroll down until this pattern stops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) this gives you the end of the firmware inside the boot_services_code? file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) 5. "dd if=boot_services_code? of=firmware bs=1 skip=<begin-addr> count=<len>"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) will extract the firmware for you. Inspect the firmware file in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) hexeditor to make sure you got the dd parameters correct.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) 6. Copy it to /lib/firmware under the expected name to test it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) 7. If the extracted firmware works, you can use the found info to fill an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) efi_embedded_fw_desc struct to describe it, run "sha256sum firmware"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) to get the sha256sum to put in the sha256 field.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags