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@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@0 { + u-boot,dm-pre-reloc; + compatible = "fs_loader"; + storage_device = "mmc"; + devpart = "0:1"; + }; + + Example for usb: + fs_loader1: fs_loader@1 { + u-boot,dm-pre-reloc; + compatible = "fs_loader"; + storage_device = "usb"; + devpart = "0:1"; + }; + + Example for sata: + fs_loader2: fs_loader@2 { + u-boot,dm-pre-reloc; + compatible = "fs_loader"; + storage_device = "sata"; + devpart = "0:1"; + }; + + Example for ubi: + fs_loader3: fs_loader@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); + }