Hi Tien, On 6 July 2018 at 02:27, <tien.fong.c...@intel.com> wrote: > From: Tien Fong Chee <tien.fong.c...@intel.com> > > Provide information about > > - overview of file system firmware loader driver model > - describe storage device and partition in device tree source > - describe fie system firmware loader API > > Signed-off-by: Tien Fong Chee <tien.fong.c...@intel.com> > --- > doc/driver-model/fs_firmware_loader.txt | 133 > ++++++++++++++++++++++++++++++++ > 1 file changed, 133 insertions(+) > create mode 100644 doc/driver-model/fs_firmware_loader.txt
Reviewed-by: Simon Glass <s...@chromium.org> A few comments below. > > diff --git a/doc/driver-model/fs_firmware_loader.txt > b/doc/driver-model/fs_firmware_loader.txt > new file mode 100644 > index 0000000..290915a > --- /dev/null > +++ b/doc/driver-model/fs_firmware_loader.txt > @@ -0,0 +1,133 @@ > +# Copyright (C) 2018 Intel Corporation <www.intel.com> > +# > +# SPDX-License-Identifier: GPL-2.0 > + > +Introduction > +============ > + > +This is file system firmware loader for U-Boot framework, which has very > close > +to some Linux Firmware API. For the details of Linux Firmware API, you can > refer > +to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html. > + > +File system firmware loader can be used to load whatever(firmware, image, > +and binary) from the storage device in file system format into target > location > +such as memory, then consumer driver such as FPGA driver can program FPGA > image > +from the target location into FPGA. > + > +To enable firmware loader, CONFIG_FS_LOADER need to be set at > +<board_name>_defconfig such as "CONFIG_FS_LOADER=y". > + > +Firmware Loader API core features > +--------------------------------- > + > +Firmware storage device described in device tree source > +------------------------------------------------------- > + For passing data like storage device phandle and partition where the > + firmware loading from to the firmware loader driver, those data could > be > + defined in fs-loader node as shown in below: > + > + Example for block device: > + fs_loader0: fs-loader@0 { > + u-boot,dm-pre-reloc; > + compatible = "u-boot,fs-loader"; > + phandlepart = <&mmc 1>; I don't like this name much. How about source-partition = <&mmc 1>; or something like that? > + }; > + > + <&mmc 1> means block storage device pointer and its partition. > + > + Above example is a description for block storage, but for UBI storage > + device, it can be described in FDT as shown in below: > + > + Example for ubi: > + fs_loader1: fs-loader@1 { > + u-boot,dm-pre-reloc; > + compatible = "u-boot,fs-loader"; > + mtdpart = "UBI", > + ubivol = "ubi0"; > + }; > + > + Then, firmware_loader property would be set with the path of fs_loader > + node under /chosen node such as: > + /{ > + chosen { > + firmware_loader = &fs_loader0; > + }; > + }; > + > + However, this driver is also designed to support U-boot environment U-Boot Please fix below also. > + variables, so all these data from FDT can be overwritten > + through the U-boot environment variable during run time. > + For examples: > + "storage_interface" - Storage interface, it can be "mmc", "usb", > "sata" > + or "ubi". > + "fw_dev_part" - Block device number and its partition, it can be > "0:1". > + "fw_ubi_mtdpart" - UBI device mtd partition, it can be "UBI". > + "fw_ubi_volume" - UBI volume, it can be "ubi0". > + > + When above environment variables are set, environment values would be > + used instead of data from FDT. > + The benefit of this design allows user to change storage attribute > data > + at run time through U-boot console and saving the setting as default > + environment values in the storage for the next power cycle, so no > + compilation is required for both driver and FDT. > + > +File system firmware Loader API > +------------------------------- > + > +int request_firmware_into_buf(struct device_platdata *plat, > + const char *name, > + void *buf, size_t size, u32 offset, > + struct firmware **firmwarep) > +-------------------------------------------------------------------- > +Load firmware into a previously allocated buffer > + > +Parameters: > + > +1. struct device_platdata *plat > + Platform data such as storage and partition firmware loading from > + > +2. const char *name > + name of firmware file > + > +3. void *buf > + address of buffer to load firmware into > + > +4. size_t size > + size of buffer > + > +5. u32 offset > + offset of a file for start reading into buffer > + > +6. struct firmware **firmwarep > + pointer to firmware image > + > +return: > + size of total read > + -ve when error > + > +Description: > + The firmware is loaded directly into the buffer pointed to by buf and > + the @firmwarep data member is pointed at buf > + > +Note: Memory would be allocated for firmware image, hence user should > + free() *firmwarep and *firmwarep->priv structs after usage of > + request_firmware_into_buf(), otherwise it will always leak memory > + while subsequent calls of request_firmware_into_buf() with the same > + *firmwarep argument. Those arguments can be free through calling API > + below release_firmware(); > + > +Example of creating firmware loader instance and calling > +request_firmware_into_buf API: > + if (uclass_get_device(UCLASS_FS_FIRMWARE_LOADER, 0, &dev)) { > + request_firmware_into_buf(dev->plat, filename, > buffer_location, > + buffer_size, offset_ofreading, &fw); > + } > + > +void release_firmware(struct firmware *firmware) > +------------------------------------------------ > +Release the resource associated with a firmware image > + > +Parameters: > + > +1. struct firmware *firmware > + Firmware resource to release > -- > 2.2.0 > Regards, Simon _______________________________________________ U-Boot mailing list U-Boot@lists.denx.de https://lists.denx.de/listinfo/u-boot
