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