From 45029758be16456189671b63137b41a5d3fe3d8d Mon Sep 17 00:00:00 2001 From: Tien Fong Chee Date: Fri, 6 Jul 2018 16:27:08 +0800 Subject: [PATCH] doc: Add new doc for file system firmware loader driver model 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 Reviewed-by: Simon Glass --- 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 0000000000..290915a959 --- /dev/null +++ b/doc/driver-model/fs_firmware_loader.txt @@ -0,0 +1,133 @@ +# Copyright (C) 2018 Intel Corporation +# +# 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 +_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@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@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.30.2