[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 at 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@lists.denx.de/msg272028.html
> > 
> > Signed-off-by: Tien Fong Chee <tien.fong.chee at 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