docs/plat/xilinx-versal.rst - filogic/atf - Gitiles

 Xilinx Versal
 =============

 Trusted Firmware-A implements the EL3 firmware layer for Xilinx Versal.
 The platform only uses the runtime part of TF-A as Xilinx Versal already has a
 BootROM (BL1) and PMC FW (BL2).

 BL31 is TF-A.
 BL32 is an optional Secure Payload.
 BL33 is the non-secure world software (U-Boot, Linux etc).

 To build:
 ```bash
 make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31
 ```

 To build bl32 TSP you have to rebuild bl31 too
 ```bash
 make CROSS_COMPILE=aarch64-none-elf- PLAT=versal SPD=tspd RESET_TO_BL31=1 bl31 bl32
 ```

 To build TF-A for JTAG DCC console
 ```bash
 make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 VERSAL_CONSOLE=dcc
 ```

 To build TF-A with Errata management interface
 ```bash
 make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 ERRATA_ABI_SUPPORT=1
 ```

 To build TF-A with Straight-Line Speculation(SLS)
 ```bash
 make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 HARDEN_SLS_ALL=1
 ```

 Xilinx Versal platform specific build options
 ---------------------------------------------

 *   `VERSAL_ATF_MEM_BASE`: Specifies the base address of the bl31 binary.
 *   `VERSAL_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary.
 *   `VERSAL_BL32_MEM_BASE`: Specifies the base address of the bl32 binary.
 *   `VERSAL_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary.

 *   `VERSAL_CONSOLE`: Select the console driver. Options:
     -   `pl011`, `pl011_0`: ARM pl011 UART 0
     -   `pl011_1`         : ARM pl011 UART 1

 *   `CPU_PWRDWN_SGI`: Select the SGI for triggering CPU power down request to
                       secondary cores on receiving power down callback from
                       firmware. Options:

     -   `0`   : SGI 0
     -   `1`   : SGI 1
     -   `2`   : SGI 2
     -   `3`   : SGI 3
     -   `4`   : SGI 4
     -   `5`   : SGI 5
     -   `6`   : SGI 6 (Default)
     -   `7`   : SGI 7

 Configurable Stack Size
 -----------------------

 The stack size in TF-A for the Versal platform is configurable.
 The custom package can define the desired stack size as per the requirement in
 the makefile as follows:

 .. code-block:: shell

     PLATFORM_STACK_SIZE := <value>

     $(eval $(call add_define,PLATFORM_STACK_SIZE))

 CUSTOM SIP Service Support
 --------------------------

 - Dedicated SMC FID ``VERSAL_SIP_SVC_CUSTOM(0x82002000)`` (32-bit) /
   ``(0xC2002000)`` (64-bit) is used by a custom package for providing
   CUSTOM SIP service.

 - By default, the platform provides a bare minimum definition for
   ``custom_smc_handler`` in this service.

 - To use this service, the custom package should implement its own SMC handler
   named ``custom_smc_handler``. Once the custom package is included in the
   TF-A build, its definition of ``custom_smc_handler`` is enabled.

 Custom Package Makefile Fragment Inclusion in TF-A Build
 --------------------------------------------------------

 - Custom package is not directly part of the TF-A source.

 - ``<CUSTOM_PKG_PATH>`` is the location where the user clones a
   custom package locally.

 - The custom package must implement a makefile fragment named
   ``custom_pkg.mk`` so it can be included in the TF-A build.

 - ``custom_pkg.mk`` should specify all the rules to include custom package
   specific header files, dependent libraries, and source files that are
   required to be part of the TF-A build.

 - When ``<CUSTOM_PKG_PATH>`` is specified in the TF-A build command,
   ``custom_pkg.mk`` is included from ``<CUSTOM_PKG_PATH>``.

 - Example TF-A build command:

 .. code-block:: shell

     make CROSS_COMPILE=aarch64-none-elf- PLAT=versal RESET_TO_BL31=1 bl31 CUSTOM_PKG_PATH=<...>

 # PLM->TF-A Parameter Passing
 ------------------------------
 The PLM populates a data structure with image information for the TF-A. The TF-A
 uses that data to hand off to the loaded images. The address of the handoff
 data structure is passed in the ```PMC_GLOBAL_GLOB_GEN_STORAGE4``` register.
 The register is free to be used by other software once the TF-A is bringing up
 further firmware images.

 Reference DEN0028E SMC calling convention
 ------------------------------------------

 Allocated subranges of Function Identifier to SIP services
 ----------------------------------------------------------

 +-----------------------+-------------------------------------------------------+
 |    SMC Function       | Identifier Service type                               |
 +-----------------------+-------------------------------------------------------+
 | 0xC2000000-0xC200FFFF | Fast SMC64 SiP Service Calls as per SMCCC Section 6.1 |
 +-----------------------+-------------------------------------------------------+

 IPI SMC call ranges
 -------------------

 +---------------------------+-----------------------------------------------------------+
 | SMC Function Identifier   | Service type                                              |
 +---------------------------+-----------------------------------------------------------+
 | 0xc2001000-0xc2001FFF     | Fast SMC64 SiP Service call range used for AMD-Xilinx IPI |
 +---------------------------+-----------------------------------------------------------+

 PM SMC call ranges for SiP SVC version 0.1
 --------------------------------------------------------

 +---------------------------+---------------------------------------------------------------------------+
 |   SMC Function Identifier |  Service type                                                             |
 +---------------------------+---------------------------------------------------------------------------+
 | 0xc2000000-0xc2000FFF     | Fast SMC64 SiP Service call range used for AMD-Xilinx Platform Management |
 +---------------------------+---------------------------------------------------------------------------+

 PM SMC call ranges for SiP SVC version 0.2
 --------------------------------------------------------

 +---------------------------+---------------------------------------------------------------------------+
 |   SMC Function Identifier |  Service type                                                             |
 +---------------------------+---------------------------------------------------------------------------+
 | 0xc2000FFF                | Fast SMC64 SiP Service call used for pass-through of AMD-Xilinx Platform  |
 |                           | Management APIs to firmware                                               |
 +---------------------------+---------------------------------------------------------------------------+
 | 0xc2000A00-0xc2000AFF     | Fast SMC64 SiP Service call range used for AMD-Xilinx Platform Management |
 |                           | specific TF-A APIs                                                        |
 +---------------------------+---------------------------------------------------------------------------+

 SMC function IDs for SiP Service queries
 ----------------------------------------

 +--------------+--------------+--------------+
 |  Service     | Call UID     | Revision     |
 +--------------+--------------+--------------+
 |  SiP Service | 0x8200_FF01  | 0x8200_FF03  |
 +--------------+--------------+--------------+

 Call UID Query – Returns a unique identifier of the service provider.

 Revision Query – Returns revision details of the service implementor.
	Xilinx Versal
	=============

	Trusted Firmware-A implements the EL3 firmware layer for Xilinx Versal.
	The platform only uses the runtime part of TF-A as Xilinx Versal already has a
	BootROM (BL1) and PMC FW (BL2).

	BL31 is TF-A.
	BL32 is an optional Secure Payload.
	BL33 is the non-secure world software (U-Boot, Linux etc).

	To build:
	```bash
	make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31
	```

	To build bl32 TSP you have to rebuild bl31 too
	```bash
	make CROSS_COMPILE=aarch64-none-elf- PLAT=versal SPD=tspd RESET_TO_BL31=1 bl31 bl32
	```

	To build TF-A for JTAG DCC console
	```bash
	make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 VERSAL_CONSOLE=dcc
	```

	To build TF-A with Errata management interface
	```bash
	make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 ERRATA_ABI_SUPPORT=1
	```

	To build TF-A with Straight-Line Speculation(SLS)
	```bash
	make RESET_TO_BL31=1 CROSS_COMPILE=aarch64-none-elf- PLAT=versal bl31 HARDEN_SLS_ALL=1
	```

	Xilinx Versal platform specific build options
	---------------------------------------------

	* `VERSAL_ATF_MEM_BASE`: Specifies the base address of the bl31 binary.
	* `VERSAL_ATF_MEM_SIZE`: Specifies the size of the memory region of the bl31 binary.
	* `VERSAL_BL32_MEM_BASE`: Specifies the base address of the bl32 binary.
	* `VERSAL_BL32_MEM_SIZE`: Specifies the size of the memory region of the bl32 binary.

	* `VERSAL_CONSOLE`: Select the console driver. Options:
	- `pl011`, `pl011_0`: ARM pl011 UART 0
	- `pl011_1` : ARM pl011 UART 1

	* `CPU_PWRDWN_SGI`: Select the SGI for triggering CPU power down request to
	secondary cores on receiving power down callback from
	firmware. Options:

	- `0` : SGI 0
	- `1` : SGI 1
	- `2` : SGI 2
	- `3` : SGI 3
	- `4` : SGI 4
	- `5` : SGI 5
	- `6` : SGI 6 (Default)
	- `7` : SGI 7

	Configurable Stack Size
	-----------------------

	The stack size in TF-A for the Versal platform is configurable.
	The custom package can define the desired stack size as per the requirement in
	the makefile as follows:

	.. code-block:: shell

	PLATFORM_STACK_SIZE := <value>

	$(eval $(call add_define,PLATFORM_STACK_SIZE))

	CUSTOM SIP Service Support
	--------------------------

	- Dedicated SMC FID ``VERSAL_SIP_SVC_CUSTOM(0x82002000)`` (32-bit) /
	``(0xC2002000)`` (64-bit) is used by a custom package for providing
	CUSTOM SIP service.

	- By default, the platform provides a bare minimum definition for
	``custom_smc_handler`` in this service.

	- To use this service, the custom package should implement its own SMC handler
	named ``custom_smc_handler``. Once the custom package is included in the
	TF-A build, its definition of ``custom_smc_handler`` is enabled.

	Custom Package Makefile Fragment Inclusion in TF-A Build
	--------------------------------------------------------

	- Custom package is not directly part of the TF-A source.

	- ``<CUSTOM_PKG_PATH>`` is the location where the user clones a
	custom package locally.

	- The custom package must implement a makefile fragment named
	``custom_pkg.mk`` so it can be included in the TF-A build.

	- ``custom_pkg.mk`` should specify all the rules to include custom package
	specific header files, dependent libraries, and source files that are
	required to be part of the TF-A build.

	- When ``<CUSTOM_PKG_PATH>`` is specified in the TF-A build command,
	``custom_pkg.mk`` is included from ``<CUSTOM_PKG_PATH>``.

	- Example TF-A build command:

	.. code-block:: shell

	make CROSS_COMPILE=aarch64-none-elf- PLAT=versal RESET_TO_BL31=1 bl31 CUSTOM_PKG_PATH=<...>

	# PLM->TF-A Parameter Passing
	------------------------------
	The PLM populates a data structure with image information for the TF-A. The TF-A
	uses that data to hand off to the loaded images. The address of the handoff
	data structure is passed in the ```PMC_GLOBAL_GLOB_GEN_STORAGE4``` register.
	The register is free to be used by other software once the TF-A is bringing up
	further firmware images.

	Reference DEN0028E SMC calling convention
	------------------------------------------

	Allocated subranges of Function Identifier to SIP services
	----------------------------------------------------------

	+-----------------------+-------------------------------------------------------+
	\| SMC Function \| Identifier Service type \|
	+-----------------------+-------------------------------------------------------+
	\| 0xC2000000-0xC200FFFF \| Fast SMC64 SiP Service Calls as per SMCCC Section 6.1 \|
	+-----------------------+-------------------------------------------------------+

	IPI SMC call ranges
	-------------------

	+---------------------------+-----------------------------------------------------------+
	\| SMC Function Identifier \| Service type \|
	+---------------------------+-----------------------------------------------------------+
	\| 0xc2001000-0xc2001FFF \| Fast SMC64 SiP Service call range used for AMD-Xilinx IPI \|
	+---------------------------+-----------------------------------------------------------+

	PM SMC call ranges for SiP SVC version 0.1
	--------------------------------------------------------

	+---------------------------+---------------------------------------------------------------------------+
	\| SMC Function Identifier \| Service type \|
	+---------------------------+---------------------------------------------------------------------------+
	\| 0xc2000000-0xc2000FFF \| Fast SMC64 SiP Service call range used for AMD-Xilinx Platform Management \|
	+---------------------------+---------------------------------------------------------------------------+

	PM SMC call ranges for SiP SVC version 0.2
	--------------------------------------------------------

	+---------------------------+---------------------------------------------------------------------------+
	\| SMC Function Identifier \| Service type \|
	+---------------------------+---------------------------------------------------------------------------+
	\| 0xc2000FFF \| Fast SMC64 SiP Service call used for pass-through of AMD-Xilinx Platform \|
	\| \| Management APIs to firmware \|
	+---------------------------+---------------------------------------------------------------------------+
	\| 0xc2000A00-0xc2000AFF \| Fast SMC64 SiP Service call range used for AMD-Xilinx Platform Management \|
	\| \| specific TF-A APIs \|
	+---------------------------+---------------------------------------------------------------------------+

	SMC function IDs for SiP Service queries
	----------------------------------------

	+--------------+--------------+--------------+
	\| Service \| Call UID \| Revision \|
	+--------------+--------------+--------------+
	\| SiP Service \| 0x8200_FF01 \| 0x8200_FF03 \|
	+--------------+--------------+--------------+

	Call UID Query – Returns a unique identifier of the service provider.

	Revision Query – Returns revision details of the service implementor.