..
 # SPDX-FileCopyrightText: <text>Copyright 2024-2026 Arm Limited and/or its
 # affiliates <open-source-office@arm.com></text>
 #
 # SPDX-License-Identifier: MIT

#########
Customize
#########

This section describes the supported customization options for Arm Zena CSS
builds and how to apply them using build environment variables. It focuses on
the configuration points exposed by the build system and highlights important
constraints to consider when deviating from the default settings.

.. note::
  The use of custom-built configurations is not automatically validated.

.. _build_env_vars:

*************************************
Available build environment variables
*************************************

The available build configuration options and the associated environment
variables are as follows:

.. warning::
  For the Zena-CSS FVP, the amount of RAM cannot exceed 4064MB. This is derived
  by taking the 4096MB total and deducting 32MB for OP-TEE. For the
  Virtualization architecture, this is split between Xen, Dom0, DomU1 and DomU2.

.. list-table:: Available Build Environment Variables
  :widths: 20 17 34 20
  :header-rows: 1

  * - Property
    - Architecture
    - Variable
    - Default
  * - Primary Compute RAM size
    - Baremetal
    - ``BAREMETAL_IMAGE_MEM_SIZE``
    - ``2016M``
  * - Primary Compute rootfs partition extra size
    - Baremetal and Virtualization (Dom0 only)
    - ``CASSINI_ROOTFS_EXTRA_SPACE``
    - ``0`` (fixed units of KB)
  * - Extra arguments for UEFI capsule generation
    - Baremetal and Virtualization
    - ``CAPSULE_EXTRA_ARGS``
    - ``--capflag PersistAcrossReset``
  * - Path to the private key file in PEM format for UEFI capsule generation and authentication
    - Baremetal and Virtualization
    - ``CAPSULE_PRIV_KEY_FILE``
    - :repo:`yocto/meta-zena-css-bsp/recipes-bsp/u-boot/files/fvp-rd-aspen/capsule_dev_priv_key.pem`
  * - Dom0 RAM size
    - Virtualization
    - ``DOM0_MEMORY_SIZE``
    - ``1024M``
  * - DomU1 RAM size
    - Virtualization
    - ``DOMU1_MEMORY_SIZE``
    - ``1024`` (fixed units of MB)
  * - DomU2 RAM size
    - Virtualization
    - ``DOMU2_MEMORY_SIZE``
    - ``1024`` (fixed units of MB)

*********************************
Using build environment variables
*********************************

The Reference Software Stack image offers customizations to build configurations
via environment variables. To use these variables, when reproducing one of the
:ref:`Use cases <rd-aspen_overview_use_cases>` using the
:ref:`reproduce instructions<rd-aspen_user_guide_reproduce>`, follow these steps:

1. Export the relevant build environment variables.

   As an example for the Baremetal architecture, to set the Primary Compute RAM
   size to 4064MB and rootfs partition extra size to 5GB, issue:

   .. code::

     export BAREMETAL_IMAGE_MEM_SIZE=4064M
     export CASSINI_ROOTFS_EXTRA_SPACE=5242880

   As an example for the Virtualization architecture, to set the Primary
   Compute Dom0 RAM size to 992MB, the DomU1 RAM size to 1536MB, keep the
   DomU2 memory size at the 1024MB default and set the Dom0 rootfs partition
   extra size to 5GB, issue:

   .. code::

     export DOM0_MEMORY_SIZE=992M
     export DOMU1_MEMORY_SIZE=1536
     export DOMU2_MEMORY_SIZE=1024
     export CASSINI_ROOTFS_EXTRA_SPACE=5242880

2. From the ``kas menu``, choose the appropriate options then choose ``Build``.
3. Remember to ``unset`` the environment variables so future builds do not
   use them.