Shrinkwrap Recipes

This page contains an unordered list of Shrinkwrap usage examples intended to demonstrate how Shrinkwrap can solve various problems.

Override Component Version and/or Location

You can change many, many configuration options by overlaying a config on top of an existing config. Here we modify the revision and remote repository of the TF-A component from its default (defined in tfa-base.yaml). You could also specify the revision as a SHA or branch.

Create a file called my-overlay.yaml:

build:
  tfa:
    repo:
      remote: https://github.com/ARM-software/arm-trusted-firmware.git
      revision: v2.9

Optionally, you can view the final, merged config as follows:

shrinkwrap process --action=merge --overlay=my-overlay.yaml ns-preload.yaml

Now do a build, passing in the overlay:

shrinkwrap build --overlay=my-overlay.yaml ns-preload.yaml

Finally, boot the config:

shrinkwrap run --rtvar=KERNEL=path/to/Image ns-preload.yaml

Reuse Existing Local Repo for Component

By default, shrinkwrap will sync the git repos for all required components to a private location (<SHRINKWRAP_BUILD>/source/<config_name>/<component_name>) the first time you build a given config. However, sometimes you want shrinkwrap to reuse a repo that already exists on your local system. In this case, Shrinkwrap will build this source into its own private build tree, leaving the source tree unmodified.

Warning

Components support building in a tree separate from the source to differing degrees. For example, TF-A will always build fiptool in the source tree, although it will build all the FW components in the correct build tree. So depending on the component you are sharing source for, you may see some build artifacts appear.

Create a file called my-overlay.yaml:

build:
  tfa:
    sourcedir: /path/to/my/tfa/git/repo
    sync: false

Now do a build, passing in the overlay:

shrinkwrap build --overlay=my-overlay.yaml ns-preload.yaml

Changing Between Arm Architecture Revisions

Shrinkwrap comes with a set of configs that can be overlaid onto the primary config in order to modify the targeted Arm architecture revision. These overlays provide all the required modifications for the TF-A build configuration and the FVP run configuration. Each architecture revision includes all mandatory features associated with that extension as well as a selection of sensible/common optional features.

Armv8.0 - Armv8.8 and Armv9.0 - Armv9.3 are currently supported. The yaml files are in the arch subdirectory of the config store. (You can see them by running the inspect command with the --all option).

The below will build the ns-edk2 config for Armv8.8 and run it on the FVP configured for the same revision.

shrinkwrap build ns-edk2.yaml --overlay=arch/v8.8.yaml
shrinkwrap run ns-edk2.yaml --rtvar=KERNEL=path/to/Image

Warning

Some components (notably TF-A) fail to incrementally build when changing their make parameters. Therefore, if you want to change the architecture revision for a config that has already been built, you must first clean tfa. See Workaround for TF-A not Noticing Modified Build Params.

Explicitly Clean a Config or Component

If the build command is invoked multiple times, Shrinkwrap will always attempt to do an incremental build. This enables a developer to modify the source and easily rebuild and run the result. However, sometimes it is useful to explicitly clean a component (or all the components within a config) to force it to be rebuilt from scratch. Shrinkwrap includes a clean command for this.

Clean an entire config (all components in config):

shrinkwrap clean ns-edk2.yaml

Clean a specific set of components from a config (in this case, clean the tfa and dt components):

shrinkwrap clean ns-edk2.yaml --filter=tfa --filter=dt

Then rebuild the config and the cleaned components are rebuilt from scratch:

shrinkwrap build ns-edk2.yaml

Workaround for TF-A not Noticing Modified Build Params

TF-A is not good at noticing when its build parameters change. If you have already built TF-A, then attempt to do an incremental build with different parameters, you rarely get what you expect. This happens a lot when using the arch/vX.Y.yaml overlays, because different architecture revisions need to specify different TF-A build parameters.

Work around this by explicitly cleaning TF-A when changing architecture revisions:

shrinkwrap build ns-edk2.yaml --overlay=arch/v8.7.yaml
shrinkwrap clean ns-edk2.yaml --filter=tfa
shrinkwrap build ns-edk2.yaml --overlay=arch/v9.3.yaml

Use a Custom FVP Version

By default, the run command will use the FVP that is bundled with the latest published shrinkwrap docker image. Sometimes you might want to use a different version though. In this case, the simplest approach is to install the FVP on your system, ensuring that the required directories are in your PATH, and invoke shrinkwrap run with the null runtime.

Shrinkwrap expects the FVP binary (e.g. FVP_Base_RevC-2xAEMvA) to be on your path. The example below shows downloading and untaring the FVP and adding the required directory to the PATH.

wget -q -O FVP_Base_RevC-2xAEMvA_11.18_16_Linux64.tgz https://developer.arm.com/-/media/Files/downloads/ecosystem-models/FVP_Base_RevC-2xAEMvA_11.18_16_Linux64.tgz
tar xf FVP_Base_RevC-2xAEMvA_11.18_16_Linux64.tgz
export PATH=$PWD/Base_RevC_AEMvA_pkg/models/Linux64_GCC-9.3:$PATH
shrinkwrap build ns-edk2.yaml
shrinkwrap --runtime=null run ns-edk2.yaml --rtvar=KERNEL=path/to/Image

Use an Alternative Device Tree

There are a couple of ways to use an alternative device tree:

All provided concrete configs that use a device tree, expose a DTB rtvar with a default value. Users can override this value to provide an externally compiled DTB at run-time.

Alternatively, the dt-base.yaml config fragment can be passed a parameter at build-time that tells it to compile an alternative DTS file. dt-base.yaml builds the device tree for the FVP_Base_RevC-2xAEMvA FVP by default and is used by all the standard concrete configs that require a device tree and is available for use in defining custom configs.

Add the following to a higher layer of the config:

build:
  dt:
    prebuild:
      - DTS=foundation-v8-gicv3-psci.dts

Note that dt-base.yaml only accepts names of dts files that already exist in the device tree repo.

Accessing the FVP over Network when using Docker/Podman

When using the docker or podman runtimes, the FVP runs inside a container. This has a different IP address to the host system. Shrinkwrap helpfully prints out the runtime environment’s IP address when starting the FVP. This is the IP address you need to use to (e.g.) connect the debugger or to SSH into the hosted Linux system.

Boot Linux with ACPI

ns-edk2.yaml uses EDK2 to boot Linux, and defaults to using the Device Tree. You can change the behaviour to boot with ACPI by passing acpi=force on the command line:

shrinkwrap run ns-edk2.yaml --rtvar=KERNEL=path/to/Image --rtvar=CMDLINE="console=ttyAMA0 earlycon=pl011,0x1c090000 root=/dev/vda ip=dhcp acpi=force"

Pass Overlay Directly on Command Line

All of the previous examples that utilize overlays, put the overlay in a yaml file and pass the file name on the command line. Here is an example that runs the FVP as normal but saves all output from UART0 to uart0.log:

Create a file called my-overlay.yaml:

run:
  params:
    -C bp.pl011_uart0.out_file: uart0.log

Now run the FVP, passing in the overlay:

shrinkwrap run ns-edk2.yaml --rtvar=KERNEL=path/to/Image --overlay=my-overlay.yaml

However, it is also possible to pass an overlay, encoded as json, directly on the command line, without the need for a file. This is useful when the overlay is small. JSON allows the entire content to be encoded on a single line without having to care about whitespace, so is suited to this purpose.

This is equivalent:

shrinkwrap run ns-edk2.yaml --rtvar=KERNEL=path/to/Image --overlay='{"run":{"params":{"-C bp.pl011_uart0.out_file":"uart0.log"}}}'

Provide SSH keys

The GIT subprocess used by Shrinkwrap to synchronise source code may require access to SSH keys. This is supported, via ssh-agent.

If ssh-agent is already running, it will be automatically detected (via the SSH_AUTH_SOCK environment variable) and used by Shrinkwrap.

Alternatively, the --ssh-agent option can be used to request Shrinkwrap to start an ssh-agent subprocess and add default keys.

shrinkwrap --ssh-agent build ...

In order to add only specified keys, the --ssh-agent-key can be used.

shrinkwrap \
  --ssh-agent-key ~/.ssh/my-first-key \
  --ssh-agent-key ~/.ssh/my-second-key \
  build ...