7dcc01343e
Currently the firmware loader only exposes one silent path for querying optional firmware, and that is firmware_request_direct(). This function also disables the sysfs fallback mechanism, which might not always be the desired behaviour [0]. This patch introduces a variations of request_firmware() that enable the caller to disable the undesired warning messages but enables the sysfs fallback mechanism. This is equivalent to adding FW_OPT_NO_WARN to the old behaviour. [0]: https://git.kernel.org/linus/c0cc00f250e1 Signed-off-by: Andres Rodriguez <andresx7@gmail.com> Reviewed-by: Kees Cook <keescook@chromium.org> Acked-by: Luis R. Rodriguez <mcgrof@kernel.org> [mcgrof: used the old API calls as the full rename is not done yet, and add the caller for when FW_LOADER is disabled, enhance documentation ] Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
76 lines
2.6 KiB
ReStructuredText
76 lines
2.6 KiB
ReStructuredText
====================
|
|
request_firmware API
|
|
====================
|
|
|
|
You would typically load firmware and then load it into your device somehow.
|
|
The typical firmware work flow is reflected below::
|
|
|
|
if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
|
|
copy_fw_to_device(fw_entry->data, fw_entry->size);
|
|
release_firmware(fw_entry);
|
|
|
|
Synchronous firmware requests
|
|
=============================
|
|
|
|
Synchronous firmware requests will wait until the firmware is found or until
|
|
an error is returned.
|
|
|
|
request_firmware
|
|
----------------
|
|
.. kernel-doc:: drivers/base/firmware_loader/main.c
|
|
:functions: request_firmware
|
|
|
|
firmware_request_nowarn
|
|
-----------------------
|
|
.. kernel-doc:: drivers/base/firmware_loader/main.c
|
|
:functions: firmware_request_nowarn
|
|
|
|
request_firmware_direct
|
|
-----------------------
|
|
.. kernel-doc:: drivers/base/firmware_loader/main.c
|
|
:functions: request_firmware_direct
|
|
|
|
request_firmware_into_buf
|
|
-------------------------
|
|
.. kernel-doc:: drivers/base/firmware_loader/main.c
|
|
:functions: request_firmware_into_buf
|
|
|
|
Asynchronous firmware requests
|
|
==============================
|
|
|
|
Asynchronous firmware requests allow driver code to not have to wait
|
|
until the firmware or an error is returned. Function callbacks are
|
|
provided so that when the firmware or an error is found the driver is
|
|
informed through the callback. request_firmware_nowait() cannot be called
|
|
in atomic contexts.
|
|
|
|
request_firmware_nowait
|
|
-----------------------
|
|
.. kernel-doc:: drivers/base/firmware_loader/main.c
|
|
:functions: request_firmware_nowait
|
|
|
|
Special optimizations on reboot
|
|
===============================
|
|
|
|
Some devices have an optimization in place to enable the firmware to be
|
|
retained during system reboot. When such optimizations are used the driver
|
|
author must ensure the firmware is still available on resume from suspend,
|
|
this can be done with firmware_request_cache() instead of requesting for the
|
|
firmware to be loaded.
|
|
|
|
firmware_request_cache()
|
|
------------------------
|
|
.. kernel-doc:: drivers/base/firmware_loader/main.c
|
|
:functions: firmware_request_cache
|
|
|
|
request firmware API expected driver use
|
|
========================================
|
|
|
|
Once an API call returns you process the firmware and then release the
|
|
firmware. For example if you used request_firmware() and it returns,
|
|
the driver has the firmware image accessible in fw_entry->{data,size}.
|
|
If something went wrong request_firmware() returns non-zero and fw_entry
|
|
is set to NULL. Once your driver is done with processing the firmware it
|
|
can call call release_firmware(fw_entry) to release the firmware image
|
|
and any related resource.
|