About mNAND Libraries#

The mNAND library consists of a set of two dynamic libraries, libnvmnand_private.so and libnvmnand_public.so.

  • libnvmnand_private.so is released only as a library.

  • libnvmnand_public.so is released as a library and source. Makefile is included to generate the library from the source. Additional required header files are included in the SDK package.

Field Firmware Update#

Overview#

Field Firmware Updates (FFU) performs updates of the devices firmware for storage devices, such as EMMC and UFS on the NVIDIA DRIVE® hardware platforms. Using this mechanism, the host deploys a new version of the firmware to the eMMC and UFS storage devices. The mNAND library provides the following interface to performing FFU operations:

  1. Get firmware version: mnand_get_fw_version()

  2. Compare firmware version: mnand_compare_fw_version()

  3. Check if FFU is ready: mnand_is_ffu_ready()

  4. Trigger FFU: mnand_ffu()

  5. Get FFU status: mnand_get_ffu_status()

Note

Refer to nvmnand.h for API usage.

The mnand_ffu() and mnand_compare_fw_version() APIs expect the firmware image name to be defined in the following format.

<firmware image>_PRN_<product identification/name>_FWVER_<firmware version string in hex format>.bin

To generate the firmware image name in the previous format, refer to the following sources:

  • PRN is the product identification or product name string that uniquely identifies the product family. It needs to be obtained from the vendor data sheet and must be replaced with <<product identification/name> in the firmware binary name. The maximum size of this string is defined in MAX_PRN_STR_LEN.

  • Firmware version is the unique version number of each firmware that is released from the vendor. Obtain it from the vendor when receiving the new firmware image. Convert this version string or number to hex and add it in place of <firmware version string in hex format>. The maximum size of this string is defined in MAX_FW_STR_LEN.

For example, if the UFS firmware image details received from the vendor are as follows, then the firmware image name should be SAMSUNG_UFS_3_1_SELENA_V5_TLC_128GB_P53_PRN_KLUDG4UHYB-B0EP_FWVER_13EC.bin

  • Firmware image : SAMSUNG_UFS_3_1_SELENA_V5 TLC_128GB_P53

  • PRN : KLUDG4UHYB-B0E

Note

PRODUCT IDENTIFICATION(16 bytes string) field of INQUIRY response

  • Firware version : 5100 (decimal) / 13EC(hex)

Note

PRODUCT REVISION LEVEL(4 bytes string stored as Hex) field of INQUIRY response

Similarly, if the following are the eMMC firmware details received from the vendor, then the firmware image name should be “SAMSUNG_eMMC_5_1_VINCENT_FETB_MLC_32GB_P63_PRN_BGUF4R_FWVER_000000059.bin”

  • Firmware image : SAMSUNG_eMMC_5_1_VINCENT_FETB_MLC_32GB_P63

  • PRN : BGUF4R

Note

PRODUCT NAME(6 bytes string) field in the CID.

  • Firmware version : 000000089(decimal)/000000059(hex)

Note

FIRMWARE_VERSION(8 bytes string stored as Hex) field in the EXT CSD

From mNAND API usage scope, use the API usage sequence below for FFU. For FFU over the air (OTA), refer to the OTA documentation.

  1. Perform the FFU operation.

  • mnand_open()

  • mnand_is_ffu_ready()

  • mnand_compare_fw_version()

  • mnand_ffu()

  • mnand_close()

  1. Storage devices firmware update takes effect only after the target reboot. Reboot the target and confirm whether the FFU operation is successful.

  • mnand_get_ffu_status().

Note

If status is set to No Information, the UFS device does not have information about the firmware update. It can be ignored. Use mnand_compare_fw_version()/mnand_ufs_compare_fw_version() to determine whether the firmware was updated successfully.

  • mnand_compare_fw_version()

FFU Security Controls#

The FFU process has the following security controls:

  1. In the Guest OS, a separate device node like - /dev/vblkdevX.ffu is enumerated for performing FFU operations. Additionally, separate access control is implemented for device management operations and FFU operations. For more information, refer to Virtual Storage Linux Storage Access Control.

  2. FFU is supported when the nvidia,allow-ffu Device Tree(DT) property is added in the UFS and eMMC controller DT nodes as shown below.

  • sdhci@3460000 { nvidia,allow-ffu; };

  • ufshci@2500000 { nvidia,allow-ffu; };

Restrictions and Recommendations#

Adhere to the following restrictions when performing the FFU:

  1. The firmware update image and the application that performs the Firmware update must be stored in the dm-verity partition that is part of the secure boot.

  2. The firmware update image name must adhere to the following naming convention:

<firmware image>_PRN_<product identification/name>_FWVER_<firmware version string in hex format>.bin

  1. Firmware update must not occur in mission mode.

  2. Storage devices FFU must be done in a controlled environment (such as a workshop) because storage devices FFU requires multiple reboots and updates of Tegra images over the air (OTA).

  3. Check the storage devices firmware release notes from storage device vendors to understand the features and updates of new firmware.

  4. Verify the first firmware update on a sample board to confirm it does not break any functionality.

  5. Check with storage vendors for the following features to understand any side effects for storage devices FFU.

    • If a power failure or other interruption occurs during FFU, confirm that the device still loads from a previous working copy of the firmware.

    • Whether the data present in the storage prior to FFU is preserved as-is after FFU completes (From Micron, the releases which are categorized as major, data may not be preserved).

    • Check with vendors whether all the device configuration settings are preserved after firmware update, except the UFS ref clk index.

  6. Complete verification by running basic read/write and device management (reference) commands after updating the storage device firmware to verify the functionality and performance.

  7. For firmware update to be effect, target reboots needs to be done and It is not possible to individually reset the UFS/eMMC device.

  8. After the firmware update is completed to a newer version, it may not be possible to revert to previous version. Contact storage vendors if you have any requirements to revert firmware updates.

On this page