| Luis R. Rodriguez | 113ccc3 | 2016-12-16 03:10:36 -0800 | [diff] [blame] | 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 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 |
| Luis R. Rodriguez | 4fde24d | 2018-05-10 13:08:48 -0700 | [diff] [blame] | 32 | userspace for the firmware request through the sysfs fallback mechanism |
| 33 | if the firmware file is not found. |
| Luis R. Rodriguez | 113ccc3 | 2016-12-16 03:10:36 -0800 | [diff] [blame] | 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 | |
