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