[U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model

[Chee, Tien Fong <tien.fong.chee@intel.com>]

On Wed, 2018-07-11 at 08:02 -0600, Simon Glass wrote:
> Hi Tien,
> 
> On 6 July 2018 at 02:27,  <tien.fong.chee@intel.com> wrote:
> > 
> > From: Tien Fong Chee <tien.fong.chee@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.chee@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 <sjg@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/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
> > +<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 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