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