1 ==================== 1 ====================
2 request_firmware API 2 request_firmware API
3 ==================== 3 ====================
4 4
5 You would typically load firmware and then loa 5 You would typically load firmware and then load it into your device somehow.
6 The typical firmware work flow is reflected be 6 The typical firmware work flow is reflected below::
7 7
8 if(request_firmware(&fw_entry, $FIRMW 8 if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
9 copy_fw_to_device(fw_entry->da 9 copy_fw_to_device(fw_entry->data, fw_entry->size);
10 release_firmware(fw_entry); 10 release_firmware(fw_entry);
11 11
12 Synchronous firmware requests 12 Synchronous firmware requests
13 ============================= 13 =============================
14 14
15 Synchronous firmware requests will wait until 15 Synchronous firmware requests will wait until the firmware is found or until
16 an error is returned. 16 an error is returned.
17 17
18 request_firmware 18 request_firmware
19 ---------------- 19 ----------------
20 .. kernel-doc:: drivers/base/firmware_loader/m 20 .. kernel-doc:: drivers/base/firmware_loader/main.c
21 :functions: request_firmware 21 :functions: request_firmware
22 22
23 firmware_request_nowarn 23 firmware_request_nowarn
24 ----------------------- 24 -----------------------
25 .. kernel-doc:: drivers/base/firmware_loader/m 25 .. kernel-doc:: drivers/base/firmware_loader/main.c
26 :functions: firmware_request_nowarn 26 :functions: firmware_request_nowarn
27 27
28 firmware_request_platform 28 firmware_request_platform
29 ------------------------- 29 -------------------------
30 .. kernel-doc:: drivers/base/firmware_loader/m 30 .. kernel-doc:: drivers/base/firmware_loader/main.c
31 :functions: firmware_request_platform 31 :functions: firmware_request_platform
32 32
33 request_firmware_direct 33 request_firmware_direct
34 ----------------------- 34 -----------------------
35 .. kernel-doc:: drivers/base/firmware_loader/m 35 .. kernel-doc:: drivers/base/firmware_loader/main.c
36 :functions: request_firmware_direct 36 :functions: request_firmware_direct
37 37
38 request_firmware_into_buf 38 request_firmware_into_buf
39 ------------------------- 39 -------------------------
40 .. kernel-doc:: drivers/base/firmware_loader/m 40 .. kernel-doc:: drivers/base/firmware_loader/main.c
41 :functions: request_firmware_into_buf 41 :functions: request_firmware_into_buf
42 42
43 Asynchronous firmware requests 43 Asynchronous firmware requests
44 ============================== 44 ==============================
45 45
46 Asynchronous firmware requests allow driver co 46 Asynchronous firmware requests allow driver code to not have to wait
47 until the firmware or an error is returned. Fu 47 until the firmware or an error is returned. Function callbacks are
48 provided so that when the firmware or an error 48 provided so that when the firmware or an error is found the driver is
49 informed through the callback. request_firmwar 49 informed through the callback. request_firmware_nowait() cannot be called
50 in atomic contexts. 50 in atomic contexts.
51 51
52 request_firmware_nowait 52 request_firmware_nowait
53 ----------------------- 53 -----------------------
54 .. kernel-doc:: drivers/base/firmware_loader/m 54 .. kernel-doc:: drivers/base/firmware_loader/main.c
55 :functions: request_firmware_nowait 55 :functions: request_firmware_nowait
56 56
57 Special optimizations on reboot 57 Special optimizations on reboot
58 =============================== 58 ===============================
59 59
60 Some devices have an optimization in place to 60 Some devices have an optimization in place to enable the firmware to be
61 retained during system reboot. When such optim 61 retained during system reboot. When such optimizations are used the driver
62 author must ensure the firmware is still avail 62 author must ensure the firmware is still available on resume from suspend,
63 this can be done with firmware_request_cache() 63 this can be done with firmware_request_cache() instead of requesting for the
64 firmware to be loaded. 64 firmware to be loaded.
65 65
66 firmware_request_cache() 66 firmware_request_cache()
67 ------------------------ 67 ------------------------
68 .. kernel-doc:: drivers/base/firmware_loader/m 68 .. kernel-doc:: drivers/base/firmware_loader/main.c
69 :functions: firmware_request_cache 69 :functions: firmware_request_cache
70 70
71 request firmware API expected driver use 71 request firmware API expected driver use
72 ======================================== 72 ========================================
73 73
74 Once an API call returns you process the firmw 74 Once an API call returns you process the firmware and then release the
75 firmware. For example if you used request_firm 75 firmware. For example if you used request_firmware() and it returns,
76 the driver has the firmware image accessible i 76 the driver has the firmware image accessible in fw_entry->{data,size}.
77 If something went wrong request_firmware() ret 77 If something went wrong request_firmware() returns non-zero and fw_entry
78 is set to NULL. Once your driver is done with 78 is set to NULL. Once your driver is done with processing the firmware it
79 can call release_firmware(fw_entry) to release 79 can call release_firmware(fw_entry) to release the firmware image
80 and any related resource. 80 and any related resource.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.