81 lines · plain
1====================2request_firmware API3====================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 requests13=============================14 15Synchronous firmware requests will wait until the firmware is found or until16an error is returned.17 18request_firmware19----------------20.. kernel-doc:: drivers/base/firmware_loader/main.c21 :functions: request_firmware22 23firmware_request_nowarn24-----------------------25.. kernel-doc:: drivers/base/firmware_loader/main.c26 :functions: firmware_request_nowarn27 28firmware_request_platform29-------------------------30.. kernel-doc:: drivers/base/firmware_loader/main.c31 :functions: firmware_request_platform32 33request_firmware_direct34-----------------------35.. kernel-doc:: drivers/base/firmware_loader/main.c36 :functions: request_firmware_direct37 38request_firmware_into_buf39-------------------------40.. kernel-doc:: drivers/base/firmware_loader/main.c41 :functions: request_firmware_into_buf42 43Asynchronous firmware requests44==============================45 46Asynchronous firmware requests allow driver code to not have to wait47until the firmware or an error is returned. Function callbacks are48provided so that when the firmware or an error is found the driver is49informed through the callback. request_firmware_nowait() cannot be called50in atomic contexts.51 52request_firmware_nowait53-----------------------54.. kernel-doc:: drivers/base/firmware_loader/main.c55 :functions: request_firmware_nowait56 57Special optimizations on reboot58===============================59 60Some devices have an optimization in place to enable the firmware to be61retained during system reboot. When such optimizations are used the driver62author must ensure the firmware is still available on resume from suspend,63this can be done with firmware_request_cache() instead of requesting for the64firmware to be loaded.65 66firmware_request_cache()67------------------------68.. kernel-doc:: drivers/base/firmware_loader/main.c69 :functions: firmware_request_cache70 71request firmware API expected driver use72========================================73 74Once an API call returns you process the firmware and then release the75firmware. 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_entry78is set to NULL. Once your driver is done with processing the firmware it79can call release_firmware(fw_entry) to release the firmware image80and any related resource.81