1 # Copyright (C) 2018 Intel Corporation <www.intel.com>
3 # SPDX-License-Identifier: GPL-2.0
8 This is file system firmware loader for U-Boot framework, which has very close
9 to some Linux Firmware API. For the details of Linux Firmware API, you can refer
10 to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html.
12 File system firmware loader can be used to load whatever(firmware, image,
13 and binary) from the storage device in file system format into target location
14 such as memory, then consumer driver such as FPGA driver can program FPGA image
15 from the target location into FPGA.
17 To enable firmware loader, CONFIG_FS_LOADER need to be set at
18 <board_name>_defconfig such as "CONFIG_FS_LOADER=y".
20 Firmware Loader API core features
21 ---------------------------------
23 Firmware storage device described in device tree source
24 -------------------------------------------------------
25 For passing data like storage device phandle and partition where the
26 firmware loading from to the firmware loader driver, those data could be
27 defined in fs-loader node as shown in below:
29 Example for block device:
30 fs_loader0: fs-loader@0 {
32 compatible = "u-boot,fs-loader";
33 phandlepart = <&mmc 1>;
36 <&mmc 1> means block storage device pointer and its partition.
38 Above example is a description for block storage, but for UBI storage
39 device, it can be described in FDT as shown in below:
42 fs_loader1: fs-loader@1 {
44 compatible = "u-boot,fs-loader";
49 Then, firmware_loader property would be set with the path of fs_loader
50 node under /chosen node such as:
53 firmware_loader = &fs_loader0;
57 However, this driver is also designed to support U-boot environment
58 variables, so all these data from FDT can be overwritten
59 through the U-boot environment variable during run time.
61 "storage_interface" - Storage interface, it can be "mmc", "usb", "sata"
63 "fw_dev_part" - Block device number and its partition, it can be "0:1".
64 "fw_ubi_mtdpart" - UBI device mtd partition, it can be "UBI".
65 "fw_ubi_volume" - UBI volume, it can be "ubi0".
67 When above environment variables are set, environment values would be
68 used instead of data from FDT.
69 The benefit of this design allows user to change storage attribute data
70 at run time through U-boot console and saving the setting as default
71 environment values in the storage for the next power cycle, so no
72 compilation is required for both driver and FDT.
74 File system firmware Loader API
75 -------------------------------
77 int request_firmware_into_buf(struct udevice *dev,
79 void *buf, size_t size, u32 offset)
80 --------------------------------------------------------------------
81 Load firmware into a previously allocated buffer
85 1. struct udevice *dev
86 An instance of a driver
92 address of buffer to load firmware into
98 offset of a file for start reading into buffer
105 The firmware is loaded directly into the buffer pointed to by buf
107 Example of creating firmware loader instance and calling
108 request_firmware_into_buf API:
109 if (uclass_get_device(UCLASS_FS_FIRMWARE_LOADER, 0, &dev)) {
110 request_firmware_into_buf(dev, filename, buffer_location,
111 buffer_size, offset_ofreading);