Documentation/driver-api/firmware/fw_upload.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================
   4 Firmware Upload API
   5 ===================
   6
   7 A device driver that registers with the firmware loader will expose
   8 persistent sysfs nodes to enable users to initiate firmware updates for
   9 that device.  It is the responsibility of the device driver and/or the
  10 device itself to perform any validation on the data received. Firmware
  11 upload uses the same *loading* and *data* sysfs files described in the
  12 documentation for firmware fallback. It also adds additional sysfs files
  13 to provide status on the transfer of the firmware image to the device.
  14
  15 Register for firmware upload
  16 ============================
  17
  18 A device driver registers for firmware upload by calling
  19 firmware_upload_register(). Among the parameter list is a name to
  20 identify the device under /sys/class/firmware. A user may initiate a
  21 firmware upload by echoing a 1 to the *loading* sysfs file for the target
  22 device. Next, the user writes the firmware image to the *data* sysfs
  23 file. After writing the firmware data, the user echos 0 to the *loading*
  24 sysfs file to signal completion. Echoing 0 to *loading* also triggers the
  25 transfer of the firmware to the lower-lever device driver in the context
  26 of a kernel worker thread.
  27
  28 To use the firmware upload API, write a driver that implements a set of
  29 ops.  The probe function calls firmware_upload_register() and the remove
  30 function calls firmware_upload_unregister() such as::
  31
  32         static const struct fw_upload_ops m10bmc_ops = {
  33                 .prepare = m10bmc_sec_prepare,
  34                 .write = m10bmc_sec_write,
  35                 .poll_complete = m10bmc_sec_poll_complete,
  36                 .cancel = m10bmc_sec_cancel,
  37                 .cleanup = m10bmc_sec_cleanup,
  38         };
  39
  40         static int m10bmc_sec_probe(struct platform_device *pdev)
  41         {
  42                 const char *fw_name, *truncate;
  43                 struct m10bmc_sec *sec;
  44                 struct fw_upload *fwl;
  45                 unsigned int len;
  46
  47                 sec = devm_kzalloc(&pdev->dev, sizeof(*sec), GFP_KERNEL);
  48                 if (!sec)
  49                         return -ENOMEM;
  50
  51                 sec->dev = &pdev->dev;
  52                 sec->m10bmc = dev_get_drvdata(pdev->dev.parent);
  53                 dev_set_drvdata(&pdev->dev, sec);
  54
  55                 fw_name = dev_name(sec->dev);
  56                 truncate = strstr(fw_name, ".auto");
  57                 len = (truncate) ? truncate - fw_name : strlen(fw_name);
  58                 sec->fw_name = kmemdup_nul(fw_name, len, GFP_KERNEL);
  59
  60                 fwl = firmware_upload_register(THIS_MODULE, sec->dev, sec->fw_name,
  61                                                &m10bmc_ops, sec);
  62                 if (IS_ERR(fwl)) {
  63                         dev_err(sec->dev, "Firmware Upload driver failed to start\n");
  64                         kfree(sec->fw_name);
  65                         return PTR_ERR(fwl);
  66                 }
  67
  68                 sec->fwl = fwl;
  69                 return 0;
  70         }
  71
  72         static int m10bmc_sec_remove(struct platform_device *pdev)
  73         {
  74                 struct m10bmc_sec *sec = dev_get_drvdata(&pdev->dev);
  75
  76                 firmware_upload_unregister(sec->fwl);
  77                 kfree(sec->fw_name);
  78                 return 0;
  79         }
  80
  81 firmware_upload_register
  82 ------------------------
  83 .. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.c
  84    :identifiers: firmware_upload_register
  85
  86 firmware_upload_unregister
  87 --------------------------
  88 .. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.c
  89    :identifiers: firmware_upload_unregister
  90
  91 Firmware Upload Ops
  92 -------------------
  93 .. kernel-doc:: include/linux/firmware.h
  94    :identifiers: fw_upload_ops
  95
  96 Firmware Upload Progress Codes
  97 ------------------------------
  98 The following progress codes are used internally by the firmware loader.
  99 Corresponding strings are reported through the status sysfs node that
 100 is described below and are documented in the ABI documentation.
 101
 102 .. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.h
 103    :identifiers: fw_upload_prog
 104
 105 Firmware Upload Error Codes
 106 ---------------------------
 107 The following error codes may be returned by the driver ops in case of
 108 failure:
 109
 110 .. kernel-doc:: include/linux/firmware.h
 111    :identifiers: fw_upload_err
 112
 113 Sysfs Attributes
 114 ================
 115
 116 In addition to the *loading* and *data* sysfs files, there are additional
 117 sysfs files to monitor the status of the data transfer to the target
 118 device and to determine the final pass/fail status of the transfer.
 119 Depending on the device and the size of the firmware image, a firmware
 120 update could take milliseconds or minutes.
 121
 122 The additional sysfs files are:
 123
 124 * status - provides an indication of the progress of a firmware update
 125 * error - provides error information for a failed firmware update
 126 * remaining_size - tracks the data transfer portion of an update
 127 * cancel - echo 1 to this file to cancel the update