doc/driver-model/fs_firmware_loader.txt

   1 # Copyright (C) 2018 Intel Corporation <www.intel.com>
   2 #
   3 # SPDX-License-Identifier:    GPL-2.0
   4
   5 Introduction
   6 ============
   7
   8 This is file system firmware loader for U-Boot framework, which has very close
   9 to some Linux Firmware API. For the details of Linux Firmware API, you can refer
  10 to https://01.org/linuxgraphics/gfx-docs/drm/driver-api/firmware/index.html.
  11
  12 File system firmware loader can be used to load whatever(firmware, image,
  13 and binary) from the storage device in file system format into target location
  14 such as memory, then consumer driver such as FPGA driver can program FPGA image
  15 from the target location into FPGA.
  16
  17 To enable firmware loader, CONFIG_FS_LOADER need to be set at
  18 <board_name>_defconfig such as "CONFIG_FS_LOADER=y".
  19
  20 Firmware Loader API core features
  21 ---------------------------------
  22
  23 Firmware storage device described in device tree source
  24 -------------------------------------------------------
  25         For passing data like storage device phandle and partition where the
  26         firmware loading from to the firmware loader driver, those data could be
  27         defined in fs-loader node as shown in below:
  28
  29         Example for block device:
  30         fs_loader0: fs-loader@0 {
  31                 u-boot,dm-pre-reloc;
  32                 compatible = "u-boot,fs-loader";
  33                 phandlepart = <&mmc 1>;
  34         };
  35
  36         <&mmc 1> means block storage device pointer and its partition.
  37
  38         Above example is a description for block storage, but for UBI storage
  39         device, it can be described in FDT as shown in below:
  40
  41         Example for ubi:
  42         fs_loader1: fs-loader@1 {
  43                 u-boot,dm-pre-reloc;
  44                 compatible = "u-boot,fs-loader";
  45                 mtdpart = "UBI",
  46                 ubivol = "ubi0";
  47         };
  48
  49         Then, firmware_loader property would be set with the path of fs_loader
  50         node under /chosen node such as:
  51         /{
  52                 chosen {
  53                         firmware_loader = &fs_loader0;
  54                 };
  55         };
  56
  57         However, this driver is also designed to support U-boot environment
  58         variables, so all these data from FDT can be overwritten
  59         through the U-boot environment variable during run time.
  60         For examples:
  61         "storage_interface" - Storage interface, it can be "mmc", "usb", "sata"
  62                                                   or "ubi".
  63         "fw_dev_part" - Block device number and its partition, it can be "0:1".
  64         "fw_ubi_mtdpart" - UBI device mtd partition, it can be "UBI".
  65         "fw_ubi_volume" - UBI volume, it can be "ubi0".
  66
  67         When above environment variables are set, environment values would be
  68         used instead of data from FDT.
  69         The benefit of this design allows user to change storage attribute data
  70         at run time through U-boot console and saving the setting as default
  71         environment values in the storage for the next power cycle, so no
  72         compilation is required for both driver and FDT.
  73
  74 File system firmware Loader API
  75 -------------------------------
  76
  77 int request_firmware_into_buf(struct device_platdata *plat,
  78                                  const char *name,
  79                                  void *buf, size_t size, u32 offset,
  80                                  struct firmware **firmwarep)
  81 --------------------------------------------------------------------
  82 Load firmware into a previously allocated buffer
  83
  84 Parameters:
  85
  86 1. struct device_platdata *plat
  87         Platform data such as storage and partition firmware loading from
  88
  89 2. const char *name
  90         name of firmware file
  91
  92 3. void *buf
  93         address of buffer to load firmware into
  94
  95 4. size_t size
  96         size of buffer
  97
  98 5. u32 offset
  99         offset of a file for start reading into buffer
 100
 101 6. struct firmware **firmwarep
 102         pointer to firmware image
 103
 104 return:
 105         size of total read
 106         -ve when error
 107
 108 Description:
 109         The firmware is loaded directly into the buffer pointed to by buf and
 110         the @firmwarep data member is pointed at buf
 111
 112 Note: Memory would be allocated for firmware image, hence user should
 113           free() *firmwarep and *firmwarep->priv structs after usage of
 114           request_firmware_into_buf(), otherwise it will always leak memory
 115           while subsequent calls of request_firmware_into_buf() with the same
 116           *firmwarep argument. Those arguments can be free through calling API
 117           below release_firmware();
 118
 119 Example of creating firmware loader instance and calling
 120 request_firmware_into_buf API:
 121         if (uclass_get_device(UCLASS_FS_FIRMWARE_LOADER, 0, &dev)) {
 122                 request_firmware_into_buf(dev->plat, filename, buffer_location,
 123                                          buffer_size, offset_ofreading, &fw);
 124         }
 125
 126 void release_firmware(struct firmware *firmware)
 127 ------------------------------------------------
 128 Release the resource associated with a firmware image
 129
 130 Parameters:
 131
 132 1. struct firmware *firmware
 133         Firmware resource to release