[U-Boot] [PATCH] doc: Document for generic firmware loader

[U-Boot] [PATCH] doc: Document for generic firmware loader

[tien.fong.chee at intel.com]

From: Tien Fong Chee <tien.fong.chee@intel.com>

This is initial draft document about generic firmware loader.
The intention of this patch is open for discussion, and final version
will be included together with next version release of generic firmware
loader patchset. Current V3 generic firmware loader patchset can be
reviewed from
https://www.mail-archive.com/u-boot at lists.denx.de/msg272028.html

Signed-off-by: Tien Fong Chee <tien.fong.chee@intel.com>
---
 doc/README.firmware_loader |   77 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 77 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.firmware_loader

diff --git a/doc/README.firmware_loader b/doc/README.firmware_loader
new file mode 100644
index 0000000..d250723
--- /dev/null
+++ b/doc/README.firmware_loader
@@ -0,0 +1,77 @@
+/*
+ * Copyright (C) 2017 Intel Corporation <www.intel.com>
+ *
+ * SPDX-License-Identifier:    GPL-2.0
+ */
+
+Introduction
+------------
+This is 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.
+
+Firmware loader can be used to load whatever(firmware, image, and binary) from
+the flash 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.
+
+Firmware Loader API core features
+---------------------------------
+=> Firmware storage device partition search
+   ----------------------------------------
+   =>	Default storage device partition search set for mmc, usb and sata
+	as shown in below:
+	static struct device_location default_locations[] = {
+		{
+			.name = "mmc",
+			.devpart = "0:1",
+		},
+		{
+			.name = "usb",
+			.devpart = "0:1",
+		},
+		{
+			.name = "sata",
+			.devpart = "0:1",
+		},
+	};
+
+	However, the default storage device .devpart value can be overwritten
+	with value which is defined in the environment variable "FW_DEV_PART".
+	For example: env_set("FW_DEV_PART", "0:2");
+
+Firmware Loader API
+-------------------
+=> int request_firmware_into_buf(struct firmware **firmware_p,
+			      const char *name,
+			      struct device_location *location,
+			      void *buf, size_t size, u32 offset)
+   --------------------------------------------------------------
+   =>	Load firmware into a previously allocated buffer
+
+	Parameters:
+	struct firmware **firmware_p
+		pointer to firmware image
+
+	const char *name
+		name of firmware file
+
+	struct device_location *location
+		an array of supported firmware location
+
+	void *buf
+		address of buffer to load firmware into
+
+	size_t size
+		size of buffer
+
+	u32 offset
+		offset of a file for start reading into buffer
+
+	return: size of total read
+	   	-ve when error
+	
+	Description:
+	The firmware is loaded directly into the buffer pointed to by buf and
+ 	the @firmware_p data member is pointed at buf.
+
-- 
1.7.7.4

[U-Boot] [PATCH] doc: Document for generic firmware loader

[Lukasz Majewski]

Hi Tien,

> From: Tien Fong Chee <tien.fong.chee@intel.com>
> 
> This is initial draft document about generic firmware loader.
> The intention of this patch is open for discussion, and final version
> will be included together with next version release of generic
> firmware loader patchset. Current V3 generic firmware loader patchset
> can be reviewed from
> https://www.mail-archive.com/u-boot at lists.denx.de/msg272028.html
> 
> Signed-off-by: Tien Fong Chee <tien.fong.chee@intel.com>
> ---
>  doc/README.firmware_loader |   77
> ++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 77
> insertions(+), 0 deletions(-) create mode 100644
> doc/README.firmware_loader
> 
> diff --git a/doc/README.firmware_loader b/doc/README.firmware_loader
> new file mode 100644
> index 0000000..d250723
> --- /dev/null
> +++ b/doc/README.firmware_loader
> @@ -0,0 +1,77 @@
> +/*
> + * Copyright (C) 2017 Intel Corporation <www.intel.com>
> + *
> + * SPDX-License-Identifier:    GPL-2.0
> + */
> +
> +Introduction
> +------------
> +This is 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.
> + +Firmware loader can be used to load whatever(firmware, image, and
> binary) from +the flash in file system format into target location
	  ^^^^^^^^^^^^^^ I suppose that you mean - load binary image
	  from file system put on flash?

> such as memory, then +consumer driver such as FPGA driver can program
> FPGA image from the target +location into FPGA.
> +
> +Firmware Loader API core features
> +---------------------------------
> +=> Firmware storage device partition search  
> +   ----------------------------------------
> +   =>	Default storage device partition search set for mmc,
> usb and sata
> +	as shown in below:
> +	static struct device_location default_locations[] = {
> +		{
> +			.name = "mmc",
> +			.devpart = "0:1",
> +		},
> +		{
> +			.name = "usb",
> +			.devpart = "0:1",
> +		},
> +		{
> +			.name = "sata",
> +			.devpart = "0:1",
> +		},
> +	};
> +
> +	However, the default storage device .devpart value can be
> overwritten
> +	with value which is defined in the environment variable
> "FW_DEV_PART".
> +	For example: env_set("FW_DEV_PART", "0:2");
			      ^^^^^^^^^^ - u-boot normally uses lower
			      case for env variable naming.

> +
> +Firmware Loader API
> +-------------------
> +=> int request_firmware_into_buf(struct firmware **firmware_p,  
> +			      const char *name,
> +			      struct device_location *location,
> +			      void *buf, size_t size, u32 offset)
> +   --------------------------------------------------------------
> +   =>	Load firmware into a previously allocated buffer
> +
> +	Parameters:
> +	struct firmware **firmware_p
> +		pointer to firmware image
> +
> +	const char *name
> +		name of firmware file
> +
> +	struct device_location *location
> +		an array of supported firmware location
> +
> +	void *buf
> +		address of buffer to load firmware into
> +
> +	size_t size
> +		size of buffer
> +
> +	u32 offset
> +		offset of a file for start reading into buffer
> +
> +	return: size of total read
> +	   	-ve when error
> +	
> +	Description:
> +	The firmware is loaded directly into the buffer pointed to
> by buf and
> + 	the @firmware_p data member is pointed at buf.
> +



Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20171218/7283ae6b/attachment.sig>

[U-Boot] [PATCH] doc: Document for generic firmware loader

[Chee, Tien Fong]

On Isn, 2017-12-18 at 10:28 +0100, Lukasz Majewski wrote:
> Hi Tien,
> 
> > 
> > From: Tien Fong Chee <tien.fong.chee@intel.com>
> > 
> > This is initial draft document about generic firmware loader.
> > The intention of this patch is open for discussion, and final
> > version
> > will be included together with next version release of generic
> > firmware loader patchset. Current V3 generic firmware loader
> > patchset
> > can be reviewed from
> > https://www.mail-archive.com/u-boot at lists.denx.de/msg272028.html
> > 
> > Signed-off-by: Tien Fong Chee <tien.fong.chee@intel.com>
> > ---
> >  doc/README.firmware_loader |   77
> > ++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 77
> > insertions(+), 0 deletions(-) create mode 100644
> > doc/README.firmware_loader
> > 
> > diff --git a/doc/README.firmware_loader
> > b/doc/README.firmware_loader
> > new file mode 100644
> > index 0000000..d250723
> > --- /dev/null
> > +++ b/doc/README.firmware_loader
> > @@ -0,0 +1,77 @@
> > +/*
> > + * Copyright (C) 2017 Intel Corporation <www.intel.com>
> > + *
> > + * SPDX-License-Identifier:    GPL-2.0
> > + */
> > +
> > +Introduction
> > +------------
> > +This is 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/inde
> > x.html.
> > + +Firmware loader can be used to load whatever(firmware, image,
> > and
> > binary) from +the flash in file system format into target location
> 	  ^^^^^^^^^^^^^^ I suppose that you mean - load binary image
> 	  from file system put on flash?
> 
Yes, you are right.
> > 
> > such as memory, then +consumer driver such as FPGA driver can
> > program
> > FPGA image from the target +location into FPGA.
> > +
> > +Firmware Loader API core features
> > +---------------------------------
> > +=> Firmware storage device partition search  
> > +   ----------------------------------------
> > +   =>	Default storage device partition search set for mmc,
> > usb and sata
> > +	as shown in below:
> > +	static struct device_location default_locations[] = {
> > +		{
> > +			.name = "mmc",
> > +			.devpart = "0:1",
> > +		},
> > +		{
> > +			.name = "usb",
> > +			.devpart = "0:1",
> > +		},
> > +		{
> > +			.name = "sata",
> > +			.devpart = "0:1",
> > +		},
> > +	};
> > +
> > +	However, the default storage device .devpart value can be
> > overwritten
> > +	with value which is defined in the environment variable
> > "FW_DEV_PART".
> > +	For example: env_set("FW_DEV_PART", "0:2");
> 			      ^^^^^^^^^^ - u-boot normally uses lower
> 			      case for env variable naming.
> 
okay, i will switch to lower case.
> > 
> > +
> > +Firmware Loader API
> > +-------------------
> > +=> int request_firmware_into_buf(struct firmware **firmware_p,  
> > +			      const char *name,
> > +			      struct device_location *location,
> > +			      void *buf, size_t size, u32 offset)
> > +   --------------------------------------------------------------
> > +   =>	Load firmware into a previously allocated buffer
> > +
> > +	Parameters:
> > +	struct firmware **firmware_p
> > +		pointer to firmware image
> > +
> > +	const char *name
> > +		name of firmware file
> > +
> > +	struct device_location *location
> > +		an array of supported firmware location
> > +
> > +	void *buf
> > +		address of buffer to load firmware into
> > +
> > +	size_t size
> > +		size of buffer
> > +
> > +	u32 offset
> > +		offset of a file for start reading into buffer
> > +
> > +	return: size of total read
> > +	   	-ve when error
> > +	
> > +	Description:
> > +	The firmware is loaded directly into the buffer pointed to
> > by buf and
> > + 	the @firmware_p data member is pointed at buf.
> > +
> 
> 
> Best regards,
> 
> Lukasz Majewski
> 
> --
> 
> DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
> HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
> Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de