| 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 |
|