| 1 |
============== |
| 2 |
Firmware cache |
| 3 |
============== |
| 4 |
|
| 5 |
When Linux resumes from suspend some device drivers require firmware lookups to |
| 6 |
re-initialize devices. During resume there may be a period of time during which |
| 7 |
firmware lookups are not possible, during this short period of time firmware |
| 8 |
requests will fail. Time is of essence though, and delaying drivers to wait for |
| 9 |
the root filesystem for firmware delays user experience with device |
| 10 |
functionality. In order to support these requirements the firmware |
| 11 |
infrastructure implements a firmware cache for device drivers for most API |
| 12 |
calls, automatically behind the scenes. |
| 13 |
|
| 14 |
The firmware cache makes using certain firmware API calls safe during a device |
| 15 |
driver's suspend and resume callback. Users of these API calls needn't cache |
| 16 |
the firmware by themselves for dealing with firmware loss during system resume. |
| 17 |
|
| 18 |
The firmware cache works by requesting for firmware prior to suspend and |
| 19 |
caching it in memory. Upon resume device drivers using the firmware API will |
| 20 |
have access to the firmware immediately, without having to wait for the root |
| 21 |
filesystem to mount or dealing with possible race issues with lookups as the |
| 22 |
root filesystem mounts. |
| 23 |
|
| 24 |
Some implementation details about the firmware cache setup: |
| 25 |
|
| 26 |
* The firmware cache is setup by adding a devres entry for each device that |
| 27 |
uses all synchronous call except :c:func:`request_firmware_into_buf`. |
| 28 |
|
| 29 |
* If an asynchronous call is used the firmware cache is only set up for a |
| 30 |
device if the second argument (uevent) to request_firmware_nowait() is |
| 31 |
true. When uevent is true it requests that a kobject uevent be sent to |
| 32 |
userspace for the firmware request through the sysfs fallback mechanism |
| 33 |
if the firmware file is not found. |
| 34 |
|
| 35 |
* If the firmware cache is determined to be needed as per the above two |
| 36 |
criteria the firmware cache is setup by adding a devres entry for the |
| 37 |
device making the firmware request. |
| 38 |
|
| 39 |
* The firmware devres entry is maintained throughout the lifetime of the |
| 40 |
device. This means that even if you release_firmware() the firmware cache |
| 41 |
will still be used on resume from suspend. |
| 42 |
|
| 43 |
* The timeout for the fallback mechanism is temporarily reduced to 10 seconds |
| 44 |
as the firmware cache is set up during suspend, the timeout is set back to |
| 45 |
the old value you had configured after the cache is set up. |
| 46 |
|
| 47 |
* Upon suspend any pending non-uevent firmware requests are killed to avoid |
| 48 |
stalling the kernel, this is done with kill_requests_without_uevent(). Kernel |
| 49 |
calls requiring the non-uevent therefore need to implement their own firmware |
| 50 |
cache mechanism but must not use the firmware API on suspend. |
| 51 |
|