1 .. SPDX-License-Identifier: GPL-2.0+
2 .. Copyright (C) 2018-2019 Intel Corporation <www.intel.com>
4 File System Firmware Loader
5 ===========================
7 This is file system firmware loader for U-Boot framework, which has very close
8 to some Linux Firmware API. For the details of Linux Firmware API, you can refer
9 to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html.
11 File system firmware loader can be used to load whatever(firmware, image,
12 and binary) from the storage device in file system format into target location
13 such as memory, then consumer driver such as FPGA driver can program FPGA image
14 from the target location into FPGA.
16 To enable firmware loader, CONFIG_FS_LOADER need to be set at
17 <board_name>_defconfig such as "CONFIG_FS_LOADER=y".
19 Firmware Loader API core features
20 ---------------------------------
22 Firmware storage device described in device tree source
23 -------------------------------------------------------
24 For passing data like storage device phandle and partition where the
25 firmware loading from to the firmware loader driver, those data could be
26 defined in fs-loader node as shown in below:
28 Example for block device::
30 fs_loader0: fs-loader {
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:
43 fs_loader1: fs-loader {
45 compatible = "u-boot,fs-loader";
50 Then, firmware-loader property can be added with any device node, which
51 driver would use the firmware loader for loading.
53 The value of the firmware-loader property should be set with phandle
54 of the fs-loader node. For example::
56 firmware-loader = <&fs_loader0>;
58 If there are majority of devices using the same fs-loader node, then
59 firmware-loader property can be added under /chosen node instead of
60 adding to each of device node.
66 firmware-loader = <&fs_loader0>;
70 In each respective driver of devices using firmware loader, the firmware
71 loaded instance should be created by DT phandle.
73 For example of getting DT phandle from /chosen and creating instance:
77 chosen_node = ofnode_path("/chosen");
78 if (!ofnode_valid(chosen_node)) {
79 debug("/chosen node was not found.\n");
83 phandle_p = ofnode_get_property(chosen_node, "firmware-loader", &size);
85 debug("firmware-loader property was not found.\n");
89 phandle = fdt32_to_cpu(*phandle_p);
90 ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER,
95 Firmware loader driver is also designed to support U-boot environment
96 variables, so all these data from FDT can be overwritten
97 through the U-boot environment variable during run time.
102 Storage interface, it can be "mmc", "usb", "sata" or "ubi".
104 Block device number and its partition, it can be "0:1".
106 UBI device mtd partition, it can be "UBI".
108 UBI volume, it can be "ubi0".
110 When above environment variables are set, environment values would be
111 used instead of data from FDT.
112 The benefit of this design allows user to change storage attribute data
113 at run time through U-boot console and saving the setting as default
114 environment values in the storage for the next power cycle, so no
115 compilation is required for both driver and FDT.
117 File system firmware Loader API
118 -------------------------------
122 int request_firmware_into_buf(struct udevice *dev,
124 void *buf, size_t size, u32 offset)
126 Load firmware into a previously allocated buffer
130 * struct udevice \*dev: An instance of a driver
131 * const char \*name: name of firmware file
132 * void \*buf: address of buffer to load firmware into
133 * size_t size: size of buffer
134 * u32 offset: offset of a file for start reading into buffer
141 The firmware is loaded directly into the buffer pointed to by buf
143 Example of calling request_firmware_into_buf API after creating firmware loader
148 ret = uclass_get_device_by_phandle_id(UCLASS_FS_FIRMWARE_LOADER,
153 request_firmware_into_buf(dev, filename, buffer_location, buffer_size,