1113ccc38SLuis R. Rodriguez==================== 2113ccc38SLuis R. Rodriguezrequest_firmware API 3113ccc38SLuis R. Rodriguez==================== 4113ccc38SLuis R. Rodriguez 5113ccc38SLuis R. RodriguezYou would typically load firmware and then load it into your device somehow. 6113ccc38SLuis R. RodriguezThe typical firmware work flow is reflected below:: 7113ccc38SLuis R. Rodriguez 8113ccc38SLuis R. Rodriguez if(request_firmware(&fw_entry, $FIRMWARE, device) == 0) 9113ccc38SLuis R. Rodriguez copy_fw_to_device(fw_entry->data, fw_entry->size); 10113ccc38SLuis R. Rodriguez release_firmware(fw_entry); 11113ccc38SLuis R. Rodriguez 12113ccc38SLuis R. RodriguezSynchronous firmware requests 13113ccc38SLuis R. Rodriguez============================= 14113ccc38SLuis R. Rodriguez 15113ccc38SLuis R. RodriguezSynchronous firmware requests will wait until the firmware is found or until 16113ccc38SLuis R. Rodriguezan error is returned. 17113ccc38SLuis R. Rodriguez 18113ccc38SLuis R. Rodriguezrequest_firmware 19113ccc38SLuis R. Rodriguez---------------- 20df9267f1SHans de Goede.. kernel-doc:: drivers/base/firmware_loader/main.c 21113ccc38SLuis R. Rodriguez :functions: request_firmware 22113ccc38SLuis R. Rodriguez 237dcc0134SAndres Rodriguezfirmware_request_nowarn 247dcc0134SAndres Rodriguez----------------------- 257dcc0134SAndres Rodriguez.. kernel-doc:: drivers/base/firmware_loader/main.c 267dcc0134SAndres Rodriguez :functions: firmware_request_nowarn 277dcc0134SAndres Rodriguez 28e4c2c0ffSHans de Goedefirmware_request_platform 29e4c2c0ffSHans de Goede------------------------- 30e4c2c0ffSHans de Goede.. kernel-doc:: drivers/base/firmware_loader/main.c 31e4c2c0ffSHans de Goede :functions: firmware_request_platform 32e4c2c0ffSHans de Goede 33113ccc38SLuis R. Rodriguezrequest_firmware_direct 34113ccc38SLuis R. Rodriguez----------------------- 35df9267f1SHans de Goede.. kernel-doc:: drivers/base/firmware_loader/main.c 36113ccc38SLuis R. Rodriguez :functions: request_firmware_direct 37113ccc38SLuis R. Rodriguez 38113ccc38SLuis R. Rodriguezrequest_firmware_into_buf 39113ccc38SLuis R. Rodriguez------------------------- 40df9267f1SHans de Goede.. kernel-doc:: drivers/base/firmware_loader/main.c 41113ccc38SLuis R. Rodriguez :functions: request_firmware_into_buf 42113ccc38SLuis R. Rodriguez 43113ccc38SLuis R. RodriguezAsynchronous firmware requests 44113ccc38SLuis R. Rodriguez============================== 45113ccc38SLuis R. Rodriguez 46113ccc38SLuis R. RodriguezAsynchronous firmware requests allow driver code to not have to wait 47113ccc38SLuis R. Rodriguezuntil the firmware or an error is returned. Function callbacks are 48113ccc38SLuis R. Rodriguezprovided so that when the firmware or an error is found the driver is 49113ccc38SLuis R. Rodriguezinformed through the callback. request_firmware_nowait() cannot be called 50113ccc38SLuis R. Rodriguezin atomic contexts. 51113ccc38SLuis R. Rodriguez 52113ccc38SLuis R. Rodriguezrequest_firmware_nowait 53113ccc38SLuis R. Rodriguez----------------------- 54df9267f1SHans de Goede.. kernel-doc:: drivers/base/firmware_loader/main.c 55113ccc38SLuis R. Rodriguez :functions: request_firmware_nowait 56113ccc38SLuis R. Rodriguez 575d42c96eSLuis R. RodriguezSpecial optimizations on reboot 585d42c96eSLuis R. Rodriguez=============================== 595d42c96eSLuis R. Rodriguez 605d42c96eSLuis R. RodriguezSome devices have an optimization in place to enable the firmware to be 615d42c96eSLuis R. Rodriguezretained during system reboot. When such optimizations are used the driver 625d42c96eSLuis R. Rodriguezauthor must ensure the firmware is still available on resume from suspend, 63b93815d0SAndres Rodriguezthis can be done with firmware_request_cache() instead of requesting for the 64b93815d0SAndres Rodriguezfirmware to be loaded. 655d42c96eSLuis R. Rodriguez 665d42c96eSLuis R. Rodriguezfirmware_request_cache() 67b93815d0SAndres Rodriguez------------------------ 68df9267f1SHans de Goede.. kernel-doc:: drivers/base/firmware_loader/main.c 695d42c96eSLuis R. Rodriguez :functions: firmware_request_cache 705d42c96eSLuis R. Rodriguez 71113ccc38SLuis R. Rodriguezrequest firmware API expected driver use 72113ccc38SLuis R. Rodriguez======================================== 73113ccc38SLuis R. Rodriguez 74113ccc38SLuis R. RodriguezOnce an API call returns you process the firmware and then release the 75113ccc38SLuis R. Rodriguezfirmware. For example if you used request_firmware() and it returns, 76113ccc38SLuis R. Rodriguezthe driver has the firmware image accessible in fw_entry->{data,size}. 77113ccc38SLuis R. RodriguezIf something went wrong request_firmware() returns non-zero and fw_entry 78113ccc38SLuis R. Rodriguezis set to NULL. Once your driver is done with processing the firmware it 79*726b5bd3SRandy Dunlapcan call release_firmware(fw_entry) to release the firmware image 80113ccc38SLuis R. Rodriguezand any related resource. 81