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