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