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 Considerations for suspend and resume
  48 =====================================
  49
  50 During suspend and resume only the built-in firmware and the firmware cache
  51 elements of the firmware API can be used. This is managed by fw_pm_notify().
  52
  53 fw_pm_notify
  54 ------------
  55 .. kernel-doc:: drivers/base/firmware_class.c
  56    :functions: fw_pm_notify
  57
  58 request firmware API expected driver use
  59 ========================================
  60
  61 Once an API call returns you process the firmware and then release the
  62 firmware. For example if you used request_firmware() and it returns,
  63 the driver has the firmware image accessible in fw_entry->{data,size}.
  64 If something went wrong request_firmware() returns non-zero and fw_entry
  65 is set to NULL. Once your driver is done with processing the firmware it
  66 can call call release_firmware(fw_entry) to release the firmware image
  67 and any related resource.