u-boot/doc/driver-model/fs_firmware_loader.txt
Tien Fong Chee 45029758be 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 <tien.fong.chee@intel.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
2018-09-28 20:22:33 -04:00

133 lines
4.3 KiB
Text

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