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