1=================== 2Fallback mechanisms 3=================== 4 5A fallback mechanism is supported to allow to overcome failures to do a direct 6filesystem lookup on the root filesystem or when the firmware simply cannot be 7installed for practical reasons on the root filesystem. The kernel 8configuration 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 23Note that this means when having this configuration: 24 25CONFIG_FW_LOADER_USER_HELPER=y 26CONFIG_FW_LOADER_USER_HELPER_FALLBACK=n 27 28the kobject uevent fallback mechanism will never take effect even 29for request_firmware_nowait() when uevent is set to true. 30 31Justifying the firmware fallback mechanism 32========================================== 33 34Direct filesystem lookups may fail for a variety of reasons. Known reasons for 35this are worth itemizing and documenting as it justifies the need for the 36fallback 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 * It cannot be installed into the root filesystem 46 * The firmware provides very unique device specific data tailored for 47 the unit gathered with local information. An example is calibration 48 data for WiFi chipsets for mobile devices. This calibration data is 49 not common to all units, but tailored per unit. Such information may 50 be installed on a separate flash partition other than where the root 51 filesystem is provided. 52 53Types of fallback mechanisms 54============================ 55 56There are really two fallback mechanisms available using one shared sysfs 57interface as a loading facility: 58 59* Kobject uevent fallback mechanism 60* Custom fallback mechanism 61 62First lets document the shared sysfs loading facility. 63 64Firmware sysfs loading facility 65=============================== 66 67In order to help device drivers upload firmware using a fallback mechanism 68the firmware infrastructure creates a sysfs interface to enable userspace 69to load and indicate when firmware is ready. The sysfs directory is created 70via fw_create_instance(). This call creates a new struct device named after 71the firmware requested, and establishes it in the device hierarchy by 72associating the device used to make the request as the device's parent. 73The sysfs directory's file attributes are defined and controlled through 74the new device's class (firmware_class) and group (fw_dev_attr_groups). 75This is actually where the original firmware_class module name came from, 76given that originally the only firmware loading mechanism available was the 77mechanism we now use as a fallback mechanism, which registers a struct class 78firmware_class. Because the attributes exposed are part of the module name, the 79module name firmware_class cannot be renamed in the future, to ensure backward 80compatibility with old userspace. 81 82To load firmware using the sysfs interface we expose a loading indicator, 83and a file upload firmware into: 84 85 * /sys/$DEVPATH/loading 86 * /sys/$DEVPATH/data 87 88To upload firmware you will echo 1 onto the loading file to indicate 89you are loading firmware. You then write the firmware into the data file, 90and you notify the kernel the firmware is ready by echo'ing 0 onto 91the loading file. 92 93The firmware device used to help load firmware using sysfs is only created if 94direct firmware loading fails and if the fallback mechanism is enabled for your 95firmware request, this is set up with fw_load_from_user_helper(). It is 96important to re-iterate that no device is created if a direct filesystem lookup 97succeeded. 98 99Using:: 100 101 echo 1 > /sys/$DEVPATH/loading 102 103Will clean any previous partial load at once and make the firmware API 104return an error. When loading firmware the firmware_class grows a buffer 105for the firmware in PAGE_SIZE increments to hold the image as it comes in. 106 107firmware_data_read() and firmware_loading_show() are just provided for the 108test_firmware driver for testing, they are not called in normal use or 109expected to be used regularly by userspace. 110 111Firmware kobject uevent fallback mechanism 112========================================== 113 114Since a device is created for the sysfs interface to help load firmware as a 115fallback mechanism userspace can be informed of the addition of the device by 116relying on kobject uevents. The addition of the device into the device 117hierarchy means the fallback mechanism for firmware loading has been initiated. 118For details of implementation refer to fw_load_sysfs_fallback(), in particular 119on the use of dev_set_uevent_suppress() and kobject_uevent(). 120 121The kernel's kobject uevent mechanism is implemented in lib/kobject_uevent.c, 122it issues uevents to userspace. As a supplement to kobject uevents Linux 123distributions could also enable CONFIG_UEVENT_HELPER_PATH, which makes use of 124core kernel's usermode helper (UMH) functionality to call out to a userspace 125helper for kobject uevents. In practice though no standard distribution has 126ever used the CONFIG_UEVENT_HELPER_PATH. If CONFIG_UEVENT_HELPER_PATH is 127enabled this binary would be called each time kobject_uevent_env() gets called 128in the kernel for each kobject uevent triggered. 129 130Different implementations have been supported in userspace to take advantage of 131this fallback mechanism. When firmware loading was only possible using the 132sysfs mechanism the userspace component "hotplug" provided the functionality of 133monitoring for kobject events. Historically this was superseded be systemd's 134udev, however firmware loading support was removed from udev as of systemd 135commit be2ea723b1d0 ("udev: remove userspace firmware loading support") 136as of v217 on August, 2014. This means most Linux distributions today are 137not using or taking advantage of the firmware fallback mechanism provided 138by kobject uevents. This is specially exacerbated due to the fact that most 139distributions today disable CONFIG_FW_LOADER_USER_HELPER_FALLBACK. 140 141Refer to do_firmware_uevent() for details of the kobject event variables 142setup. The variables currently passed to userspace with a "kobject add" 143event are: 144 145* FIRMWARE=firmware name 146* TIMEOUT=timeout value 147* ASYNC=whether or not the API request was asynchronous 148 149By default DEVPATH is set by the internal kernel kobject infrastructure. 150Below is an example simple kobject uevent script:: 151 152 # Both $DEVPATH and $FIRMWARE are already provided in the environment. 153 MY_FW_DIR=/lib/firmware/ 154 echo 1 > /sys/$DEVPATH/loading 155 cat $MY_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data 156 echo 0 > /sys/$DEVPATH/loading 157 158Firmware custom fallback mechanism 159================================== 160 161Users of the request_firmware_nowait() call have yet another option available 162at their disposal: rely on the sysfs fallback mechanism but request that no 163kobject uevents be issued to userspace. The original logic behind this 164was that utilities other than udev might be required to lookup firmware 165in non-traditional paths -- paths outside of the listing documented in the 166section 'Direct filesystem lookup'. This option is not available to any of 167the other API calls as uevents are always forced for them. 168 169Since uevents are only meaningful if the fallback mechanism is enabled 170in your kernel it would seem odd to enable uevents with kernels that do not 171have the fallback mechanism enabled in their kernels. Unfortunately we also 172rely on the uevent flag which can be disabled by request_firmware_nowait() to 173also setup the firmware cache for firmware requests. As documented above, 174the firmware cache is only set up if uevent is enabled for an API call. 175Although this can disable the firmware cache for request_firmware_nowait() 176calls, users of this API should not use it for the purposes of disabling 177the cache as that was not the original purpose of the flag. Not setting 178the uevent flag means you want to opt-in for the firmware fallback mechanism 179but you want to suppress kobject uevents, as you have a custom solution which 180will monitor for your device addition into the device hierarchy somehow and 181load firmware for you through a custom path. 182 183Firmware fallback timeout 184========================= 185 186The firmware fallback mechanism has a timeout. If firmware is not loaded 187onto the sysfs interface by the timeout value an error is sent to the 188driver. By default the timeout is set to 60 seconds if uevents are 189desirable, otherwise MAX_JIFFY_OFFSET is used (max timeout possible). 190The logic behind using MAX_JIFFY_OFFSET for non-uevents is that a custom 191solution will have as much time as it needs to load firmware. 192 193You can customize the firmware timeout by echo'ing your desired timeout into 194the following file: 195 196* /sys/class/firmware/timeout 197 198If you echo 0 into it means MAX_JIFFY_OFFSET will be used. The data type 199for the timeout is an int. 200