doc: Add new doc for file system firmware loader driver model

From: Tien Fong Chee <[email protected]>

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 <[email protected]>

---
 doc/driver-model/fs_firmware_loader.txt | 133 ++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 doc/driver-model/fs_firmware_loader.txt

doc/driver-model/fs_firmware_loader.txt new file +23 -0

new file mode 100644
index 0000000..290915a
@@ -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

doc/driver-model/fs_firmware_loader.txt new file +14 -0

+       };
+
+       <&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";
+       };

doc/driver-model/fs_firmware_loader.txt new file +76 -1

+       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

Hi Tien,

Quoted 9 lines · On 6 July 2018 at 02:27,  <[email protected]> wrote:

From: Tien Fong Chee <[email protected]>

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

Quoted 6 lines

Signed-off-by Tien Fong Chee <[email protected]>

---
 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 <[email protected]>

A few comments below.

Quoted 42 lines

doc/driver- renamed from doc/driver-model/fs_firmware_loader.txt +0 -0

model/fs_firmware_loader.txt
new file mode 100644
index 0000000..290915a

doc/driver-model/fs_firmware_loader.txt new file +8 -0

@@ -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.

doc/driver-model/fs_firmware_loader.txt new file +2 -0

+
+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

doc/driver-model/fs_firmware_loader.txt new file +11 -0

+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

Quoted 8 lines

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?

Quoted 21 lines

+       };
+
+       <&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:

doc/driver-model/fs_firmware_loader.txt new file +10 -0

+
+       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:

Quoted 8 lines

+       /{
+               chosen {
+                       firmware_loader = &fs_loader0; +               };
+       };
+
+       However, this driver is also designed to support U-boot environment

U-Boot

Please fix below also.

Quoted 98 lines

+       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.

doc/driver-model/fs_firmware_loader.txt new file +7 -0

+
+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)
+----------------------------------------------------------------
----

doc/driver-model/fs_firmware_loader.txt new file +6 -0

+Load firmware into a previously allocated buffer
+
+Parameters:
+
+1. struct device_platdata *plat
+       Platform data such as storage and partition firmware

loading from

doc/driver-model/fs_firmware_loader.txt new file +22 -0

+
+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

doc/driver-model/fs_firmware_loader.txt new file +2 -0

+
+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();

doc/driver-model/fs_firmware_loader.txt new file +4 -0

+
+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);
+       }

doc/driver-model/fs_firmware_loader.txt new file +9 -1

+
+void release_firmware(struct firmware *firmware)
+------------------------------------------------
+Release the resource associated with a firmware image
+
+Parameters:
+
+1. struct firmware *firmware
+       Firmware resource to release
--

Quoted 2 lines

2.2.0

Regards,
Simon

From: Tien Fong Chee <[email protected]>

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 <[email protected]>

Reviewed-by Simon Glass <[email protected]>