[U-Boot,1/3] doc: Add new doc for file system firmware loader driver model

Message ID 1526462501-9586-2-git-send-email-tien.fong.chee@intel.com
State Superseded
Delegated to: Tom Rini
Headers show
Series
  • Generic file system firmware loader DM
Related show

Commit Message

Chee, Tien Fong May 16, 2018, 9:21 a.m.
From: Tien Fong Chee <tien.fong.chee@intel.com>

Provide information about

- overview of file system firmware loader driver model
- describe default storage device 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 |  100 +++++++++++++++++++++++++++++++
 1 files changed, 100 insertions(+), 0 deletions(-)
 create mode 100644 doc/driver-model/fs_firmware_loader.txt

Comments

Tom Rini May 16, 2018, 12:48 p.m. | #1
On Wed, May 16, 2018 at 05:21:39PM +0800, 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 default storage device 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 |  100 +++++++++++++++++++++++++++++++
>  1 files changed, 100 insertions(+), 0 deletions(-)
>  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..167660a
> --- /dev/null
> +++ b/doc/driver-model/fs_firmware_loader.txt
> @@ -0,0 +1,100 @@
> +/*
> + * Copyright (C) 2018 Intel Corporation <www.intel.com>
> + *
> + * SPDX-License-Identifier:    GPL-2.0
> + */

As this isn't code please don't put a code header up for the first
comment block.  Frankly I'd rather see an rST comment block up front
even with the rest being plain text as long term I imagine we'll move to
rST.
Chee, Tien Fong May 17, 2018, 4:27 a.m. | #2
On Wed, 2018-05-16 at 08:48 -0400, Tom Rini wrote:
> On Wed, May 16, 2018 at 05:21:39PM +0800, 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 default storage device 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 |  100
> > +++++++++++++++++++++++++++++++
> >  1 files changed, 100 insertions(+), 0 deletions(-)
> >  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..167660a
> > --- /dev/null
> > +++ b/doc/driver-model/fs_firmware_loader.txt
> > @@ -0,0 +1,100 @@
> > +/*
> > + * Copyright (C) 2018 Intel Corporation <www.intel.com>
> > + *
> > + * SPDX-License-Identifier:    GPL-2.0
> > + */
> As this isn't code please don't put a code header up for the first
> comment block.  Frankly I'd rather see an rST comment block up front
> even with the rest being plain text as long term I imagine we'll move
> to
> rST.
> 
Okay, i will remove the license and changing it to rST format.
Tom Rini May 17, 2018, 11:11 a.m. | #3
On Thu, May 17, 2018 at 04:27:27AM +0000, Chee, Tien Fong wrote:
> On Wed, 2018-05-16 at 08:48 -0400, Tom Rini wrote:
> > On Wed, May 16, 2018 at 05:21:39PM +0800, 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 default storage device 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 |  100
> > > +++++++++++++++++++++++++++++++
> > >  1 files changed, 100 insertions(+), 0 deletions(-)
> > >  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..167660a
> > > --- /dev/null
> > > +++ b/doc/driver-model/fs_firmware_loader.txt
> > > @@ -0,0 +1,100 @@
> > > +/*
> > > + * Copyright (C) 2018 Intel Corporation <www.intel.com>
> > > + *
> > > + * SPDX-License-Identifier:    GPL-2.0
> > > + */
> > As this isn't code please don't put a code header up for the first
> > comment block.  Frankly I'd rather see an rST comment block up front
> > even with the rest being plain text as long term I imagine we'll move
> > to
> > rST.
> > 
> Okay, i will remove the license and changing it to rST format.

You don't need to remove it, just move it :)
Chee, Tien Fong May 18, 2018, 4:46 a.m. | #4
On Thu, 2018-05-17 at 07:11 -0400, Tom Rini wrote:
> On Thu, May 17, 2018 at 04:27:27AM +0000, Chee, Tien Fong wrote:
> > 
> > On Wed, 2018-05-16 at 08:48 -0400, Tom Rini wrote:
> > > 
> > > On Wed, May 16, 2018 at 05:21:39PM +0800, tien.fong.chee@intel.co
> > > m
> > > wrote:
> > > 
> > > > 
> > > > 
> > > > From: Tien Fong Chee <tien.fong.chee@intel.com>
> > > > 
> > > > Provide information about
> > > > 
> > > > - overview of file system firmware loader driver model
> > > > - describe default storage device 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 |  100
> > > > +++++++++++++++++++++++++++++++
> > > >  1 files changed, 100 insertions(+), 0 deletions(-)
> > > >  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..167660a
> > > > --- /dev/null
> > > > +++ b/doc/driver-model/fs_firmware_loader.txt
> > > > @@ -0,0 +1,100 @@
> > > > +/*
> > > > + * Copyright (C) 2018 Intel Corporation <www.intel.com>
> > > > + *
> > > > + * SPDX-License-Identifier:    GPL-2.0
> > > > + */
> > > As this isn't code please don't put a code header up for the
> > > first
> > > comment block.  Frankly I'd rather see an rST comment block up
> > > front
> > > even with the rest being plain text as long term I imagine we'll
> > > move
> > > to
> > > rST.
> > > 
> > Okay, i will remove the license and changing it to rST format.
> You don't need to remove it, just move it :)
> 
Ohh....i just need to change the license and copyright header to rST
format?

Patch

diff --git a/doc/driver-model/fs_firmware_loader.txt b/doc/driver-model/fs_firmware_loader.txt
new file mode 100644
index 0000000..167660a
--- /dev/null
+++ b/doc/driver-model/fs_firmware_loader.txt
@@ -0,0 +1,100 @@ 
+/*
+ * 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 driver model, 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
+   ----------------------------------------
+   =>	Example of default storage device partition search set for mmc, usb,
+	sata and ubi as shown in below:
+	Example for mmc:
+	fs_loader {
+		u-boot,dm-pre-reloc;
+		compatible = "fs_loader";
+		storage_device = "mmc";
+		devpart = "0:1";
+	};
+
+	Example for usb:
+	fs_loader {
+		u-boot,dm-pre-reloc;
+		compatible = "fs_loader";
+		storage_device = "usb";
+		devpart = "0:1";
+	};
+
+	Example for sata:
+	fs_loader {
+		u-boot,dm-pre-reloc;
+		compatible = "fs_loader";
+		storage_device = "sata";
+		devpart = "0:1";
+	};
+
+	Example for ubi:
+	fs_loader {
+		u-boot,dm-pre-reloc;
+		compatible = "fs_loader";
+		storage_device = "ubi";
+		mtdpart = "UBI",
+		ubivol = "ubi0";
+	};
+
+
+	However, the default fs_loader with property devpart, mtdpart, and
+	ubivol values can be overwritten with value which is defined in the
+	environment variable "fw_dev_part", "fw_ubi_mtdpart", and
+	"fw_ubi_volume" respectively.
+	For example: env_set("fw_dev_part", "0:2");
+
+File system firmware Loader API
+-------------------------------
+=> int request_firmware_into_buf(struct udevice *dev,
+				 struct firmware **firmware_p,
+				 const char *name,
+				 void *buf, size_t size, u32 offset)
+   -----------------------------------------------------------------
+   =>	Load firmware into a previously allocated buffer
+
+	Parameters:
+	struct udevice *dev
+		An instance of a driver
+
+	struct firmware **firmware_p
+		pointer to firmware image
+
+	const char *name
+		name of firmware file
+
+	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.