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