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