128 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===================4Firmware Upload API5===================6 7A device driver that registers with the firmware loader will expose8persistent sysfs nodes to enable users to initiate firmware updates for9that device. It is the responsibility of the device driver and/or the10device itself to perform any validation on the data received. Firmware11upload uses the same *loading* and *data* sysfs files described in the12documentation for firmware fallback. It also adds additional sysfs files13to provide status on the transfer of the firmware image to the device.14 15Register for firmware upload16============================17 18A device driver registers for firmware upload by calling19firmware_upload_register(). Among the parameter list is a name to20identify the device under /sys/class/firmware. A user may initiate a21firmware upload by echoing a 1 to the *loading* sysfs file for the target22device. Next, the user writes the firmware image to the *data* sysfs23file. After writing the firmware data, the user echos 0 to the *loading*24sysfs file to signal completion. Echoing 0 to *loading* also triggers the25transfer of the firmware to the lower-lever device driver in the context26of a kernel worker thread.27 28To use the firmware upload API, write a driver that implements a set of29ops. The probe function calls firmware_upload_register() and the remove30function 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 81firmware_upload_register82------------------------83.. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.c84 :identifiers: firmware_upload_register85 86firmware_upload_unregister87--------------------------88.. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.c89 :identifiers: firmware_upload_unregister90 91Firmware Upload Ops92-------------------93.. kernel-doc:: include/linux/firmware.h94 :identifiers: fw_upload_ops95 96Firmware Upload Progress Codes97------------------------------98The following progress codes are used internally by the firmware loader.99Corresponding strings are reported through the status sysfs node that100is described below and are documented in the ABI documentation.101 102.. kernel-doc:: drivers/base/firmware_loader/sysfs_upload.h103 :identifiers: fw_upload_prog104 105Firmware Upload Error Codes106---------------------------107The following error codes may be returned by the driver ops in case of108failure:109 110.. kernel-doc:: include/linux/firmware.h111 :identifiers: fw_upload_err112 113Sysfs Attributes114================115 116In addition to the *loading* and *data* sysfs files, there are additional117sysfs files to monitor the status of the data transfer to the target118device and to determine the final pass/fail status of the transfer.119Depending on the device and the size of the firmware image, a firmware120update could take milliseconds or minutes.121 122The additional sysfs files are:123 124* status - provides an indication of the progress of a firmware update125* error - provides error information for a failed firmware update126* remaining_size - tracks the data transfer portion of an update127* cancel - echo 1 to this file to cancel the update128