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

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

[tien.fong.chee at intel.com]

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

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 at 0 {
+		u-boot,dm-pre-reloc;
+		compatible = "u-boot,fs-loader";
+		phandlepart = <&mmc 1>;
+	};
+
+	<&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
+	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

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

[Simon Glass]

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/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 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>;

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.

> +       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] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model

[Chee, Tien Fong]

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

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

[Tom Rini]

On Fri, Jul 06, 2018 at 04:27:08PM +0800, tien.fong.chee at 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>
> Reviewed-by: Simon Glass <sjg@chromium.org>

Applied to u-boot/master, thanks!

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20180929/e08fc5cd/attachment.sig>