1# Copyright (C) 2018 Intel Corporation <www.intel.com>
2#
3# SPDX-License-Identifier:    GPL-2.0
4
5Introduction
6============
7
8This is file system firmware loader for U-Boot framework, which has very close
9to some Linux Firmware API. For the details of Linux Firmware API, you can refer
10to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html.
11
12File system firmware loader can be used to load whatever(firmware, image,
13and binary) from the storage device in file system format into target location
14such as memory, then consumer driver such as FPGA driver can program FPGA image
15from the target location into FPGA.
16
17To enable firmware loader, CONFIG_FS_LOADER need to be set at
18<board_name>_defconfig such as "CONFIG_FS_LOADER=y".
19
20Firmware Loader API core features
21---------------------------------
22
23Firmware 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:
28
29	Example for block device:
30	fs_loader0: fs-loader@0 {
31		u-boot,dm-pre-reloc;
32		compatible = "u-boot,fs-loader";
33		phandlepart = <&mmc 1>;
34	};
35
36	<&mmc 1> means block storage device pointer and its partition.
37
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:
40
41	Example for ubi:
42	fs_loader1: fs-loader@1 {
43		u-boot,dm-pre-reloc;
44		compatible = "u-boot,fs-loader";
45		mtdpart = "UBI",
46		ubivol = "ubi0";
47	};
48
49	Then, firmware_loader property would be set with the path of fs_loader
50	node under /chosen node such as:
51	/{
52		chosen {
53			firmware_loader = &fs_loader0;
54		};
55	};
56
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.
60	For examples:
61	"storage_interface" - Storage interface, it can be "mmc", "usb", "sata"
62						  or "ubi".
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".
66
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.
73
74File system firmware Loader API
75-------------------------------
76
77int request_firmware_into_buf(struct device_platdata *plat,
78				 const char *name,
79				 void *buf, size_t size, u32 offset,
80				 struct firmware **firmwarep)
81--------------------------------------------------------------------
82Load firmware into a previously allocated buffer
83
84Parameters:
85
861. struct device_platdata *plat
87	Platform data such as storage and partition firmware loading from
88
892. const char *name
90	name of firmware file
91
923. void *buf
93	address of buffer to load firmware into
94
954. size_t size
96	size of buffer
97
985. u32 offset
99	offset of a file for start reading into buffer
100
1016. struct firmware **firmwarep
102	pointer to firmware image
103
104return:
105	size of total read
106	-ve when error
107
108Description:
109	The firmware is loaded directly into the buffer pointed to by buf and
110	the @firmwarep data member is pointed at buf
111
112Note: Memory would be allocated for firmware image, hence user should
113	  free() *firmwarep and *firmwarep->priv structs after usage of
114	  request_firmware_into_buf(), otherwise it will always leak memory
115	  while subsequent calls of request_firmware_into_buf() with the same
116	  *firmwarep argument. Those arguments can be free through calling API
117	  below release_firmware();
118
119Example of creating firmware loader instance and calling
120request_firmware_into_buf API:
121	if (uclass_get_device(UCLASS_FS_FIRMWARE_LOADER, 0, &dev)) {
122		request_firmware_into_buf(dev->plat, filename, buffer_location,
123					 buffer_size, offset_ofreading, &fw);
124	}
125
126void release_firmware(struct firmware *firmware)
127------------------------------------------------
128Release the resource associated with a firmware image
129
130Parameters:
131
1321. struct firmware *firmware
133	Firmware resource to release
134