.. SPDX-License-Identifier: GPL-2.0
..  (C) Copyright 2020 Xilinx, Inc.

ZYNQMP
======

About this
----------

This document describes the information about Xilinx Zynq UltraScale+ MPSOC
U-Boot support. Core support is available in arch/arm/mach-zynqmp folder.

ZynqMP boards
-------------

* zcu100 (ultra96 v1), zcu102, zcu104, zcu106 - Evaluation boards
* zc1232 - Characterization boards
* zcu111, zcu208, zcu216 - RFSOC evaluation boards
* zcu1254, zcu1275, zcu1285 - RFSOC characterization boards
* a2197 - System Controller on Versal boards
* mini - Mini U-Boot running out of OCM
* zc1751 - Characterization Processor boards
     - zc1751-xm015-dc1
     - zc1751-xm016-dc2
     - zc1751-xm017-dc3
     - zc1751-xm018-dc4
     - zc1751-xm019-dc5

Building
--------

Configure and build for zcu102 board::

   $ source arm64 toolchain
   $ export DEVICE_TREE=zynqmp-zcu102-revA
   $ make xilinx_zynqmp_virt_defconfig
   $ make

U-Boot SPL flow
---------------

For getting U-Boot SPL flow up and running it is necessary to do some additional
steps because booting device requires external images which are not the part of
U-Boot repository.

PMU firmware
^^^^^^^^^^^^
The Platform Management Unit (PMU) RAM can be loaded with a firmware (PMU
Firmware) at run-time and can be used to extend or customize the functionality
of PMU. The PMU firmware is the part of boot image (boot.bin) and it is
automatically loaded by BootROM. boot.bin can be directly generated by mkimage
tool as the part of make. If you want to create boot.bin with PMU Firmware
include please point CONFIG_PMUFW_INIT_FILE to PMU firmware binary. For example:::

  CONFIG_PMUFW_INIT_FILE="<path>/pmu.bin"

If you see below message you need to load PMU Firmware::

  PMUFW is not found - Please load it!

The second external blob is PMU Configuration object which is object which is
passed from U-Boot SPL to PMU Firmware for initial system configuration. PMU
configuration object is the part of U-Boot SPL image. For pointing to this
object please use CONFIG_ZYNQMP_SPL_PM_CFG_OBJ_FILE symbol. For example:::

  CONFIG_ZYNQMP_SPL_PM_CFG_OBJ_FILE="<path>/pmu_obj.bin"


PMU configuration object
^^^^^^^^^^^^^^^^^^^^^^^^

Object can be obtain in several ways. The easiest way is to take pm_cfg_obj.c
from SDK/Vitis design and build it:::

  $ git clone https://github.com/Xilinx/embeddedsw.git
  $ export EMBEDDED_SW=$PWD/embeddedsw
  $ gcc -c pm_cfg_obj.c -I ${EMBEDDED_SW}/lib/bsp/standalone/src/common/ -I ${EMBEDDED_SW}/lib/sw_services/xilpm/src/zynqmp/client/common/
  $ objcopy -O binary pm_cfg_obj.o pmu_obj.bin

The second way is to use tools/zynqmp_pm_cfg_obj_convert.py. For more
information about this tool please run it with -h parameter.

The third way is to extract it from Xilinx FSBL elf file. Object is starting at
XPm_ConfigObject symbol.


Arm Trusted Firmware (ATF)
^^^^^^^^^^^^^^^^^^^^^^^^^^

U-Boot itself can run from EL3 to EL1. Without ATF U-Boot runs in EL3. Boot flow
is U-Boot SPL->U-Boot in EL3. When ATF is used U-Boot normally runs in EL2. Boot
flow is U-Boot SPL->ATF->U-Boot in EL2. As the part of build process u-boot.itb
is generated. When BL31 shell variable is present u-boot.itb is generated with
ATF included. You can point to it by:::

  $ export BL31=<path>/bl31.bin

Flashing
--------

SD Card
^^^^^^^

To write an image that boots from a SD card first create a FAT32 partition
and a FAT32 filesystem on the SD card::

        sudo fdisk /dev/sdx
        sudo mkfs.vfat -F 32 /dev/sdx1

Mount the SD card and copy the SPL and U-Boot to the root directory of the
SD card::

        sudo mount -t vfat /dev/sdx1 /mnt
        sudo cp spl/boot.bin /mnt
        sudo cp u-boot.itb /mnt