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>lime2-spi
parent
bc53d2637e
commit
45029758be
@ -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 |
||||||
|
------------------------------------------------------- |
||||||
|
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 |
Loading…
Reference in new issue