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