0001 ====================
0002 request_firmware API
0003 ====================
0004
0005 You would typically load firmware and then load it into your device somehow.
0006 The typical firmware work flow is reflected below::
0007
0008 if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
0009 copy_fw_to_device(fw_entry->data, fw_entry->size);
0010 release_firmware(fw_entry);
0011
0012 Synchronous firmware requests
0013 =============================
0014
0015 Synchronous firmware requests will wait until the firmware is found or until
0016 an error is returned.
0017
0018 request_firmware
0019 ----------------
0020 .. kernel-doc:: drivers/base/firmware_loader/main.c
0021 :functions: request_firmware
0022
0023 firmware_request_nowarn
0024 -----------------------
0025 .. kernel-doc:: drivers/base/firmware_loader/main.c
0026 :functions: firmware_request_nowarn
0027
0028 firmware_request_platform
0029 -------------------------
0030 .. kernel-doc:: drivers/base/firmware_loader/main.c
0031 :functions: firmware_request_platform
0032
0033 request_firmware_direct
0034 -----------------------
0035 .. kernel-doc:: drivers/base/firmware_loader/main.c
0036 :functions: request_firmware_direct
0037
0038 request_firmware_into_buf
0039 -------------------------
0040 .. kernel-doc:: drivers/base/firmware_loader/main.c
0041 :functions: request_firmware_into_buf
0042
0043 Asynchronous firmware requests
0044 ==============================
0045
0046 Asynchronous firmware requests allow driver code to not have to wait
0047 until the firmware or an error is returned. Function callbacks are
0048 provided so that when the firmware or an error is found the driver is
0049 informed through the callback. request_firmware_nowait() cannot be called
0050 in atomic contexts.
0051
0052 request_firmware_nowait
0053 -----------------------
0054 .. kernel-doc:: drivers/base/firmware_loader/main.c
0055 :functions: request_firmware_nowait
0056
0057 Special optimizations on reboot
0058 ===============================
0059
0060 Some devices have an optimization in place to enable the firmware to be
0061 retained during system reboot. When such optimizations are used the driver
0062 author must ensure the firmware is still available on resume from suspend,
0063 this can be done with firmware_request_cache() instead of requesting for the
0064 firmware to be loaded.
0065
0066 firmware_request_cache()
0067 ------------------------
0068 .. kernel-doc:: drivers/base/firmware_loader/main.c
0069 :functions: firmware_request_cache
0070
0071 request firmware API expected driver use
0072 ========================================
0073
0074 Once an API call returns you process the firmware and then release the
0075 firmware. For example if you used request_firmware() and it returns,
0076 the driver has the firmware image accessible in fw_entry->{data,size}.
0077 If something went wrong request_firmware() returns non-zero and fw_entry
0078 is set to NULL. Once your driver is done with processing the firmware it
0079 can call release_firmware(fw_entry) to release the firmware image
0080 and any related resource.
