Revert "firmware: add sanity check on shutdown/suspend"
[muen/linux.git] / Documentation / driver-api / firmware / request_firmware.rst
1 ====================
2 request_firmware API
3 ====================
4
5 You would typically load firmware and then load it into your device somehow.
6 The 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
12 Synchronous firmware requests
13 =============================
14
15 Synchronous firmware requests will wait until the firmware is found or until
16 an error is returned.
17
18 request_firmware
19 ----------------
20 .. kernel-doc:: drivers/base/firmware_class.c
21    :functions: request_firmware
22
23 request_firmware_direct
24 -----------------------
25 .. kernel-doc:: drivers/base/firmware_class.c
26    :functions: request_firmware_direct
27
28 request_firmware_into_buf
29 -------------------------
30 .. kernel-doc:: drivers/base/firmware_class.c
31    :functions: request_firmware_into_buf
32
33 Asynchronous firmware requests
34 ==============================
35
36 Asynchronous firmware requests allow driver code to not have to wait
37 until the firmware or an error is returned. Function callbacks are
38 provided so that when the firmware or an error is found the driver is
39 informed through the callback. request_firmware_nowait() cannot be called
40 in atomic contexts.
41
42 request_firmware_nowait
43 -----------------------
44 .. kernel-doc:: drivers/base/firmware_class.c
45    :functions: request_firmware_nowait
46
47 request firmware API expected driver use
48 ========================================
49
50 Once an API call returns you process the firmware and then release the
51 firmware. For example if you used request_firmware() and it returns,
52 the driver has the firmware image accessible in fw_entry->{data,size}.
53 If something went wrong request_firmware() returns non-zero and fw_entry
54 is set to NULL. Once your driver is done with processing the firmware it
55 can call call release_firmware(fw_entry) to release the firmware image
56 and any related resource.