1*4882a593Smuzhiyun==================== 2*4882a593Smuzhiyunrequest_firmware API 3*4882a593Smuzhiyun==================== 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunYou would typically load firmware and then load it into your device somehow. 6*4882a593SmuzhiyunThe typical firmware work flow is reflected below:: 7*4882a593Smuzhiyun 8*4882a593Smuzhiyun if(request_firmware(&fw_entry, $FIRMWARE, device) == 0) 9*4882a593Smuzhiyun copy_fw_to_device(fw_entry->data, fw_entry->size); 10*4882a593Smuzhiyun release_firmware(fw_entry); 11*4882a593Smuzhiyun 12*4882a593SmuzhiyunSynchronous firmware requests 13*4882a593Smuzhiyun============================= 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunSynchronous firmware requests will wait until the firmware is found or until 16*4882a593Smuzhiyunan error is returned. 17*4882a593Smuzhiyun 18*4882a593Smuzhiyunrequest_firmware 19*4882a593Smuzhiyun---------------- 20*4882a593Smuzhiyun.. kernel-doc:: drivers/base/firmware_loader/main.c 21*4882a593Smuzhiyun :functions: request_firmware 22*4882a593Smuzhiyun 23*4882a593Smuzhiyunfirmware_request_nowarn 24*4882a593Smuzhiyun----------------------- 25*4882a593Smuzhiyun.. kernel-doc:: drivers/base/firmware_loader/main.c 26*4882a593Smuzhiyun :functions: firmware_request_nowarn 27*4882a593Smuzhiyun 28*4882a593Smuzhiyunfirmware_request_platform 29*4882a593Smuzhiyun------------------------- 30*4882a593Smuzhiyun.. kernel-doc:: drivers/base/firmware_loader/main.c 31*4882a593Smuzhiyun :functions: firmware_request_platform 32*4882a593Smuzhiyun 33*4882a593Smuzhiyunrequest_firmware_direct 34*4882a593Smuzhiyun----------------------- 35*4882a593Smuzhiyun.. kernel-doc:: drivers/base/firmware_loader/main.c 36*4882a593Smuzhiyun :functions: request_firmware_direct 37*4882a593Smuzhiyun 38*4882a593Smuzhiyunrequest_firmware_into_buf 39*4882a593Smuzhiyun------------------------- 40*4882a593Smuzhiyun.. kernel-doc:: drivers/base/firmware_loader/main.c 41*4882a593Smuzhiyun :functions: request_firmware_into_buf 42*4882a593Smuzhiyun 43*4882a593SmuzhiyunAsynchronous firmware requests 44*4882a593Smuzhiyun============================== 45*4882a593Smuzhiyun 46*4882a593SmuzhiyunAsynchronous firmware requests allow driver code to not have to wait 47*4882a593Smuzhiyununtil the firmware or an error is returned. Function callbacks are 48*4882a593Smuzhiyunprovided so that when the firmware or an error is found the driver is 49*4882a593Smuzhiyuninformed through the callback. request_firmware_nowait() cannot be called 50*4882a593Smuzhiyunin atomic contexts. 51*4882a593Smuzhiyun 52*4882a593Smuzhiyunrequest_firmware_nowait 53*4882a593Smuzhiyun----------------------- 54*4882a593Smuzhiyun.. kernel-doc:: drivers/base/firmware_loader/main.c 55*4882a593Smuzhiyun :functions: request_firmware_nowait 56*4882a593Smuzhiyun 57*4882a593SmuzhiyunSpecial optimizations on reboot 58*4882a593Smuzhiyun=============================== 59*4882a593Smuzhiyun 60*4882a593SmuzhiyunSome devices have an optimization in place to enable the firmware to be 61*4882a593Smuzhiyunretained during system reboot. When such optimizations are used the driver 62*4882a593Smuzhiyunauthor must ensure the firmware is still available on resume from suspend, 63*4882a593Smuzhiyunthis can be done with firmware_request_cache() instead of requesting for the 64*4882a593Smuzhiyunfirmware to be loaded. 65*4882a593Smuzhiyun 66*4882a593Smuzhiyunfirmware_request_cache() 67*4882a593Smuzhiyun------------------------ 68*4882a593Smuzhiyun.. kernel-doc:: drivers/base/firmware_loader/main.c 69*4882a593Smuzhiyun :functions: firmware_request_cache 70*4882a593Smuzhiyun 71*4882a593Smuzhiyunrequest firmware API expected driver use 72*4882a593Smuzhiyun======================================== 73*4882a593Smuzhiyun 74*4882a593SmuzhiyunOnce an API call returns you process the firmware and then release the 75*4882a593Smuzhiyunfirmware. For example if you used request_firmware() and it returns, 76*4882a593Smuzhiyunthe driver has the firmware image accessible in fw_entry->{data,size}. 77*4882a593SmuzhiyunIf something went wrong request_firmware() returns non-zero and fw_entry 78*4882a593Smuzhiyunis set to NULL. Once your driver is done with processing the firmware it 79*4882a593Smuzhiyuncan call release_firmware(fw_entry) to release the firmware image 80*4882a593Smuzhiyunand any related resource. 81