18c2ecf20Sopenharmony_ci==================== 28c2ecf20Sopenharmony_cirequest_firmware API 38c2ecf20Sopenharmony_ci==================== 48c2ecf20Sopenharmony_ci 58c2ecf20Sopenharmony_ciYou would typically load firmware and then load it into your device somehow. 68c2ecf20Sopenharmony_ciThe typical firmware work flow is reflected below:: 78c2ecf20Sopenharmony_ci 88c2ecf20Sopenharmony_ci if(request_firmware(&fw_entry, $FIRMWARE, device) == 0) 98c2ecf20Sopenharmony_ci copy_fw_to_device(fw_entry->data, fw_entry->size); 108c2ecf20Sopenharmony_ci release_firmware(fw_entry); 118c2ecf20Sopenharmony_ci 128c2ecf20Sopenharmony_ciSynchronous firmware requests 138c2ecf20Sopenharmony_ci============================= 148c2ecf20Sopenharmony_ci 158c2ecf20Sopenharmony_ciSynchronous firmware requests will wait until the firmware is found or until 168c2ecf20Sopenharmony_cian error is returned. 178c2ecf20Sopenharmony_ci 188c2ecf20Sopenharmony_cirequest_firmware 198c2ecf20Sopenharmony_ci---------------- 208c2ecf20Sopenharmony_ci.. kernel-doc:: drivers/base/firmware_loader/main.c 218c2ecf20Sopenharmony_ci :functions: request_firmware 228c2ecf20Sopenharmony_ci 238c2ecf20Sopenharmony_cifirmware_request_nowarn 248c2ecf20Sopenharmony_ci----------------------- 258c2ecf20Sopenharmony_ci.. kernel-doc:: drivers/base/firmware_loader/main.c 268c2ecf20Sopenharmony_ci :functions: firmware_request_nowarn 278c2ecf20Sopenharmony_ci 288c2ecf20Sopenharmony_cifirmware_request_platform 298c2ecf20Sopenharmony_ci------------------------- 308c2ecf20Sopenharmony_ci.. kernel-doc:: drivers/base/firmware_loader/main.c 318c2ecf20Sopenharmony_ci :functions: firmware_request_platform 328c2ecf20Sopenharmony_ci 338c2ecf20Sopenharmony_cirequest_firmware_direct 348c2ecf20Sopenharmony_ci----------------------- 358c2ecf20Sopenharmony_ci.. kernel-doc:: drivers/base/firmware_loader/main.c 368c2ecf20Sopenharmony_ci :functions: request_firmware_direct 378c2ecf20Sopenharmony_ci 388c2ecf20Sopenharmony_cirequest_firmware_into_buf 398c2ecf20Sopenharmony_ci------------------------- 408c2ecf20Sopenharmony_ci.. kernel-doc:: drivers/base/firmware_loader/main.c 418c2ecf20Sopenharmony_ci :functions: request_firmware_into_buf 428c2ecf20Sopenharmony_ci 438c2ecf20Sopenharmony_ciAsynchronous firmware requests 448c2ecf20Sopenharmony_ci============================== 458c2ecf20Sopenharmony_ci 468c2ecf20Sopenharmony_ciAsynchronous firmware requests allow driver code to not have to wait 478c2ecf20Sopenharmony_ciuntil the firmware or an error is returned. Function callbacks are 488c2ecf20Sopenharmony_ciprovided so that when the firmware or an error is found the driver is 498c2ecf20Sopenharmony_ciinformed through the callback. request_firmware_nowait() cannot be called 508c2ecf20Sopenharmony_ciin atomic contexts. 518c2ecf20Sopenharmony_ci 528c2ecf20Sopenharmony_cirequest_firmware_nowait 538c2ecf20Sopenharmony_ci----------------------- 548c2ecf20Sopenharmony_ci.. kernel-doc:: drivers/base/firmware_loader/main.c 558c2ecf20Sopenharmony_ci :functions: request_firmware_nowait 568c2ecf20Sopenharmony_ci 578c2ecf20Sopenharmony_ciSpecial optimizations on reboot 588c2ecf20Sopenharmony_ci=============================== 598c2ecf20Sopenharmony_ci 608c2ecf20Sopenharmony_ciSome devices have an optimization in place to enable the firmware to be 618c2ecf20Sopenharmony_ciretained during system reboot. When such optimizations are used the driver 628c2ecf20Sopenharmony_ciauthor must ensure the firmware is still available on resume from suspend, 638c2ecf20Sopenharmony_cithis can be done with firmware_request_cache() instead of requesting for the 648c2ecf20Sopenharmony_cifirmware to be loaded. 658c2ecf20Sopenharmony_ci 668c2ecf20Sopenharmony_cifirmware_request_cache() 678c2ecf20Sopenharmony_ci------------------------ 688c2ecf20Sopenharmony_ci.. kernel-doc:: drivers/base/firmware_loader/main.c 698c2ecf20Sopenharmony_ci :functions: firmware_request_cache 708c2ecf20Sopenharmony_ci 718c2ecf20Sopenharmony_cirequest firmware API expected driver use 728c2ecf20Sopenharmony_ci======================================== 738c2ecf20Sopenharmony_ci 748c2ecf20Sopenharmony_ciOnce an API call returns you process the firmware and then release the 758c2ecf20Sopenharmony_cifirmware. For example if you used request_firmware() and it returns, 768c2ecf20Sopenharmony_cithe driver has the firmware image accessible in fw_entry->{data,size}. 778c2ecf20Sopenharmony_ciIf something went wrong request_firmware() returns non-zero and fw_entry 788c2ecf20Sopenharmony_ciis set to NULL. Once your driver is done with processing the firmware it 798c2ecf20Sopenharmony_cican call release_firmware(fw_entry) to release the firmware image 808c2ecf20Sopenharmony_ciand any related resource. 81