* [U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model
@ 2018-07-06 8:27 tien.fong.chee at intel.com
2018-07-11 14:02 ` Simon Glass
2018-09-29 15:43 ` [U-Boot] [U-Boot, v4, " Tom Rini
0 siblings, 2 replies; 4+ messages in thread
From: tien.fong.chee at intel.com @ 2018-07-06 8:27 UTC (permalink / raw)
To: u-boot
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
^ permalink raw reply related [flat|nested] 4+ messages in thread* [U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model
2018-07-06 8:27 [U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model tien.fong.chee at intel.com
@ 2018-07-11 14:02 ` Simon Glass
2018-07-11 14:21 ` Chee, Tien Fong
2018-09-29 15:43 ` [U-Boot] [U-Boot, v4, " Tom Rini
1 sibling, 1 reply; 4+ messages in thread
From: Simon Glass @ 2018-07-11 14:02 UTC (permalink / raw)
To: u-boot
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
^ permalink raw reply [flat|nested] 4+ messages in thread* [U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model
2018-07-11 14:02 ` Simon Glass
@ 2018-07-11 14:21 ` Chee, Tien Fong
0 siblings, 0 replies; 4+ messages in thread
From: Chee, Tien Fong @ 2018-07-11 14:21 UTC (permalink / raw)
To: u-boot
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* [U-Boot] [U-Boot, v4, 4/6] doc: Add new doc for file system firmware loader driver model
2018-07-06 8:27 [U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model tien.fong.chee at intel.com
2018-07-11 14:02 ` Simon Glass
@ 2018-09-29 15:43 ` Tom Rini
1 sibling, 0 replies; 4+ messages in thread
From: Tom Rini @ 2018-09-29 15:43 UTC (permalink / raw)
To: u-boot
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>
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2018-09-29 15:43 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-07-06 8:27 [U-Boot] [PATCH v4 4/6] doc: Add new doc for file system firmware loader driver model tien.fong.chee at intel.com
2018-07-11 14:02 ` Simon Glass
2018-07-11 14:21 ` Chee, Tien Fong
2018-09-29 15:43 ` [U-Boot] [U-Boot, v4, " Tom Rini
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox