0001 ==============
0002 Firmware cache
0003 ==============
0004
0005 When Linux resumes from suspend some device drivers require firmware lookups to
0006 re-initialize devices. During resume there may be a period of time during which
0007 firmware lookups are not possible, during this short period of time firmware
0008 requests will fail. Time is of essence though, and delaying drivers to wait for
0009 the root filesystem for firmware delays user experience with device
0010 functionality. In order to support these requirements the firmware
0011 infrastructure implements a firmware cache for device drivers for most API
0012 calls, automatically behind the scenes.
0013
0014 The firmware cache makes using certain firmware API calls safe during a device
0015 driver's suspend and resume callback. Users of these API calls needn't cache
0016 the firmware by themselves for dealing with firmware loss during system resume.
0017
0018 The firmware cache works by requesting for firmware prior to suspend and
0019 caching it in memory. Upon resume device drivers using the firmware API will
0020 have access to the firmware immediately, without having to wait for the root
0021 filesystem to mount or dealing with possible race issues with lookups as the
0022 root filesystem mounts.
0023
0024 Some implementation details about the firmware cache setup:
0025
0026 * The firmware cache is setup by adding a devres entry for each device that
0027 uses all synchronous call except :c:func:`request_firmware_into_buf`.
0028
0029 * If an asynchronous call is used the firmware cache is only set up for a
0030 device if the second argument (uevent) to request_firmware_nowait() is
0031 true. When uevent is true it requests that a kobject uevent be sent to
0032 userspace for the firmware request through the sysfs fallback mechanism
0033 if the firmware file is not found.
0034
0035 * If the firmware cache is determined to be needed as per the above two
0036 criteria the firmware cache is setup by adding a devres entry for the
0037 device making the firmware request.
0038
0039 * The firmware devres entry is maintained throughout the lifetime of the
0040 device. This means that even if you release_firmware() the firmware cache
0041 will still be used on resume from suspend.
0042
0043 * The timeout for the fallback mechanism is temporarily reduced to 10 seconds
0044 as the firmware cache is set up during suspend, the timeout is set back to
0045 the old value you had configured after the cache is set up.
0046
0047 * Upon suspend any pending non-uevent firmware requests are killed to avoid
0048 stalling the kernel, this is done with kill_requests_without_uevent(). Kernel
0049 calls requiring the non-uevent therefore need to implement their own firmware
0050 cache mechanism but must not use the firmware API on suspend.
0051
