From mboxrd@z Thu Jan 1 00:00:00 1970 From: Chee, Tien Fong Date: Wed, 11 Jul 2018 14:21:39 +0000 Subject: [U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model In-Reply-To: References: <1530865628-17245-1-git-send-email-tien.fong.chee@intel.com> Message-ID: <1531318899.9560.6.camel@intel.com> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 8bit To: u-boot@lists.denx.de On Wed, 2018-07-11 at 08:02 -0600, Simon Glass wrote: > Hi Tien, > > On 6 July 2018 at 02:27,   wrote: > > > > From: Tien Fong Chee > > > > 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 > > --- > >  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 > > 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 > > +# > > +# 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/i > > ndex.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 > > +_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 at 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>; Okay. > > 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 at 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. Okay. > > > > > +       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