Running Arm Virtual Hardware FVPs on MacOS

This repository contains scripts that enable Arm Virtual Hardware FVPs to run via Docker on MacOS.

Prerequisites

Install Docker Desktop on Mac.

For commercial use you might require a paid subscription.

Verify proper installation by running the following commands on a terminal:

docker info

If the Docker installation is operational it prints out version information about Client and Server.

Clone the repo

Open a terminal and set the working directory where to store the Fast Model wrapper to. Then run:

git clone https://github.com/Arm-Examples/FVPs-on-Mac.git

This will create the subdirectory FVPs-on-Mac in the current working directory.

Build the Docker wrapper

Run the build script to create the Docker image and populate the bin folder with model wrappers:

./build.sh

Once this succeeds inspect the created bin folder containing a bunch of symlinks to fvp.sh. These wrappers can be used exactly like any native model executable:

./bin/FVP_MPS2_Cortex-M3 --version

Expose models to local environment

Add $(pwd)/FVPs-on-Mac/bin to PATH environment:

export PATH=$PATH:$(pwd)/FVPs-on-Mac/bin

Put this to our ~/.zshrc to make it permanent.

XQuartz setup for FVP GUI (optional)

If you want to use the FVP GUI, you need to follow some additional steps on your host OS.

1. Install XQuartz

   brew install xquartz

   The X11 tools should be installed in /opt/X11/bin. Add this directory to your PATH.

2. Ensure XQuartz allows connections from network clients

   Open Xquartz. At the top left of the screen you will find the app's menu bar. Click on Xquartz - Settings and go to the Security tab:

   

3. Allow X11 forwarding

   xhost +
   

   If you need to set up a socat relay to forward X11 display traffic in a Colima + Docker environment, be sure to allow connections from localhost to ensure proper communication with your XQuartz server.

   xhost + 127.0.0.1
   #install and setup socat relay
   brew install socat
   socat TCP-LISTEN:6000,reuseaddr,fork UNIX-CLIENT:\"$DISPLAY\"

4. Run model and check GUI is showing

   FVP_Corstone_SSE-300_Ethos-U55
   

   If you need to forward display traffic to your Mac, pass your IP address using the --display-ip command-line parameter. You can obtain your ip by calling ipconfig getifaddr en0.

   FVP_Corstone_SSE-300_Ethos-U55 --display-ip 0.1.2.3
   

   

Resources

• sorny/x11_forwarding_macos_docker.md

Run Models

Once the setup has been completed one can run Fast Models as they are installed natively.

Some restrictions still apply:

• By default, your home directory is mounted into the Docker container for file access. Hence, all files accessed (application images, configuration files) must be stored in your home directory or its subdirectories, unless you specify a different mount directory using FVP_MOUNT_DIR.

• Fast Models require an activated User Based License. The license cache stored in ~/.armlm on the host machine is always mapped into the container. Thus, the models running inside of the container reuse the license activated on the host machine.

Note

• If you do not wish to use the GUI, disable it with fvp_mps2.mps2_visualisation.disable-visualisation=1 in the FVP configuration text file.
• If you are using a UART and want to redirect to the Terminal, add fvp_mps2.UART0.out_file=- to the FVP configuration text file.
• If you want to disable the Telnet session, add fvp_mps2.telnetterminal0.start_telnet=0 to the FVP configuration text file.
• Depending on your model, the prefix fvp_mps2 might be different!

Customization

The Fast Model version and package used for creating the Docker image and wrapper scripts is configured in the file fvprc. If one wants to use another model version or custom package one can just change the values stored in this file.

Alternatively, on can set the model version for example as an environment variable overwriting the default given in fvprc. The following settings can be changed:

• FVP_VERSION: The release version triple (major.minor.patch).
• FVP_BASE_URL: The base download URL to get the model package from.
• FVP_ARCHIVE: The name of the model package archive to fetch.

The download URL is composed as ${FVP_BASE_URL}/${FVP_VERSION}/${FVP_ARCHIVE}. The created Docker image is labeled as fvp:${FVP_VERSION}. Hence, one can keep multiple versions in parallel and switch between them by just setting the environment variable to the required version.

FVP_VERSION=11.22.39 FVP_MPS2_Cortex-M3 --version

Repository structure

The repository contains the following files:

    📦
    ┣ 📂 bin           Created/updated by build.sh script
    ┣ 📄 build.sh      The script to build a Docker image
    ┣ 📄 dockerfile    The recipe used to build the Docker image
    ┣ 📄 fvp.sh        The wrapper script to launch a model executable inside a Docker container
    ┗ 📄 fvprc         The configuration file to customize default model version and package

Customising Docker Mounts

By default, your entire home directory is mounted and the container starts in your current working directory.

For better security and performance, use the FVP_MOUNT_DIR and FVP_WORKDIR ENV vars limit what's mounted:

# Mount only current directory
FVP_MOUNT_DIR=$(pwd) FVP_MPS2_Cortex-M3 --version

# Mount project root but work in subdirectory
FVP_MOUNT_DIR=/path/to/project FVP_WORKDIR=/path/to/project/build FVP_MPS2_Cortex-M3 --version