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 28firmware_request_platform 29------------------------- 30.. kernel-doc:: drivers/base/firmware_loader/main.c 31 :functions: firmware_request_platform 32 33request_firmware_direct 34----------------------- 35.. kernel-doc:: drivers/base/firmware_loader/main.c 36 :functions: request_firmware_direct 37 38request_firmware_into_buf 39------------------------- 40.. kernel-doc:: drivers/base/firmware_loader/main.c 41 :functions: request_firmware_into_buf 42 43Asynchronous firmware requests 44============================== 45 46Asynchronous firmware requests allow driver code to not have to wait 47until the firmware or an error is returned. Function callbacks are 48provided so that when the firmware or an error is found the driver is 49informed through the callback. request_firmware_nowait() cannot be called 50in atomic contexts. 51 52request_firmware_nowait 53----------------------- 54.. kernel-doc:: drivers/base/firmware_loader/main.c 55 :functions: request_firmware_nowait 56 57Special optimizations on reboot 58=============================== 59 60Some devices have an optimization in place to enable the firmware to be 61retained during system reboot. When such optimizations are used the driver 62author must ensure the firmware is still available on resume from suspend, 63this can be done with firmware_request_cache() instead of requesting for the 64firmware to be loaded. 65 66firmware_request_cache() 67------------------------ 68.. kernel-doc:: drivers/base/firmware_loader/main.c 69 :functions: firmware_request_cache 70 71request firmware API expected driver use 72======================================== 73 74Once an API call returns you process the firmware and then release the 75firmware. For example if you used request_firmware() and it returns, 76the driver has the firmware image accessible in fw_entry->{data,size}. 77If something went wrong request_firmware() returns non-zero and fw_entry 78is set to NULL. Once your driver is done with processing the firmware it 79can call release_firmware(fw_entry) to release the firmware image 80and any related resource. 81