[U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model
Chee, Tien Fong
tien.fong.chee at intel.com
Wed Jul 11 14:21:39 UTC 2018
On Wed, 2018-07-11 at 08:02 -0600, Simon Glass wrote:
> Hi Tien,
>
> On 6 July 2018 at 02:27, <tien.fong.chee at intel.com> wrote:
> >
> > From: Tien Fong Chee <tien.fong.chee at 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 at 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 at 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
More information about the U-Boot
mailing list