Documentation/driver-api/firmware/fallback-mechanisms.rst

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