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
47Considerations for suspend and resume
48=====================================
49
50During suspend and resume only the built-in firmware and the firmware cache
51elements of the firmware API can be used. This is managed by fw_pm_notify().
52
53fw_pm_notify
54------------
55.. kernel-doc:: drivers/base/firmware_class.c
56   :functions: fw_pm_notify
57
58request firmware API expected driver use
59========================================
60
61Once an API call returns you process the firmware and then release the
62firmware. For example if you used request_firmware() and it returns,
63the driver has the firmware image accessible in fw_entry->{data,size}.
64If something went wrong request_firmware() returns non-zero and fw_entry
65is set to NULL. Once your driver is done with processing the firmware it
66can call call release_firmware(fw_entry) to release the firmware image
67and any related resource.
68