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