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