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

tien.fong.chee at intel.com
2018-06-25T13:28:56Z

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 | 129 ++++++++++++++++++++++++++++++++
1 file changed, 129 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..102e14b
--- /dev/null
+++ b/doc/driver-model/fs_firmware_loader.txt
@@ -0,0 +1,129 @@
+# 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 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:
+
+ fs_loader0: fs_loader at 0 {
+ u-boot,dm-pre-reloc;
+ compatible = "fs_loader";
+ storage_device = "mmc";
+ devpart = "0:1";
+ };
+
+ Then, firmware_loader property would be set with the path of fs_loader
+ node under /chosen node such as:
+ /{
+ chosen {
+ firmware_loader = &fs_loader0;
+ };
+ };
+
+ Example of storage type and device partition search set for mmc, usb,
+ sata and ubi as shown in below:
+ Example for mmc:
+ fs_loader0: fs_loader at 0 {
+ u-boot,dm-pre-reloc;
+ compatible = "fs_loader";
+ storage_device = "mmc";
+ devpart = "0:1";
+ };
+
+ Example for usb:
+ fs_loader1: fs_loader at 1 {
+ u-boot,dm-pre-reloc;
+ compatible = "fs_loader";
+ storage_device = "usb";
+ devpart = "0:1";
+ };
+
+ Example for sata:
+ fs_loader2: fs_loader at 2 {
+ u-boot,dm-pre-reloc;
+ compatible = "fs_loader";
+ storage_device = "sata";
+ devpart = "0:1";
+ };
+
+ Example for ubi:
+ fs_loader3: fs_loader at 3 {
+ u-boot,dm-pre-reloc;
+ compatible = "fs_loader";
+ storage_device = "ubi";
+ mtdpart = "UBI",
+ ubivol = "ubi0";
+ };
+
+
+ However, the property of devpart, mtdpart, and ubivol values from
+ fs_loader node 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 device_platdata *plat,
+ struct firmware **firmware_p,
+ const char *name,
+ void *buf, size_t size, u32 offset)
+--------------------------------------------------------------------
+Load firmware into a previously allocated buffer
+
+Parameters:
+
+1. struct device_platdata *plat
+ Platform data such as storage and partition firmware loading from
+
+2. struct firmware **firmware_p
+ pointer to firmware image
+
+3. const char *name
+ name of firmware file
+
+4. void *buf
+ address of buffer to load firmware into
+
+5. size_t size
+ size of buffer
+
+6. 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
+
+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, &fw, filename,
+ buffer_location, buffer_size, offset_ofreading);
+ }
--
2.2.0