1# Running Images with a FVP 2 3The `runfvp` tool in meta-arm makes it easy to run Yocto Project disk images inside a [Fixed Virtual Platform (FVP)][FVP]. Some FVPs, such as the [Arm Architecture Models][AEM], are available free to download, but others need registration or are only available commercially. The `fvp-base` machine in meta-arm-bsp uses one of these AEM models. 4 5## Running images with `runfvp` 6 7To build images with the FVP integration, the `fvpboot` image class needs to be inherited. If the machine does not do this explicitly it can be done in `local.conf`: 8 9``` 10IMAGE_CLASSES += "fvpboot" 11``` 12 13The class will download the correct FVP and write a `.fvpconf` configuration file when an image is built. 14 15To run an image in a FVP, pass either a machine name or a `.fvpconf` path to `runfvp`. 16 17``` 18$ ./meta-arm/scripts/runfvp tmp/deploy/images/fvp-base/core-image-minimal-fvp-base.fvpconf 19``` 20 21When a machine name is passed, `runfvp` will start the latest image that has been built for that machine. This requires that the BitBake environment has been initialized (using `oe-init-build-env` or similar) as it will start BitBake to determine where the images are. 22 23``` 24$ ./meta-arm/scripts/runfvp fvp-base 25``` 26 27Note that currently meta-arm's `scripts` directory isn't in `PATH`, so a full path needs to be used. 28 29`runfvp` will automatically start terminals connected to each of the serial ports that the machine specifies. This can be controlled by using the `--terminals` option, for example `--terminals=none` will mean no terminals are started, and `--terminals=tmux` will start the terminals in [`tmux`][tmux] sessions. Alternatively, passing `--console` will connect the serial port directly to the current session, without needing to open further windows. 30 31The default terminal can also be configured by writing a [INI-style][INI] configuration file to `~/.config/runfvp.conf`: 32 33``` 34[RunFVP] 35Terminal=tmux 36``` 37 38Arbitrary options can be passed directly to the FVP by specifying them after a double dash, for example this will list all of the FVP parameters: 39 40``` 41$ runfvp fvp-base -- --list-params 42``` 43 44## Configuring machines with `fvpboot` 45 46To configure a machine so that it can be ran inside `runfvp`, a number of variables need to be set in the machine configuration file (such as `meta-arm-bsp/conf/machine/fvp-base.conf`). 47 48Note that at present these variables are not stable and their behaviour may be changed in the future. 49 50### `FVP_EXE` 51 52The name of the FVP binary itself, for example `fvp-base` uses `FVP_Base_RevC-2xAEMvA`. 53 54### `FVP_PROVIDER` 55 56The name of the recipe that provides the FVP executable set in `FVP_EXE`, for example `fvp-base` uses `fvp-base-a-aem-native`. This *must* be a `-native` recipe as the binary will be executed on the build host. 57 58There are recipes for common FVPs in meta-arm already, and writing new recipes is trivial. For FVPs which are free to download `fvp-base-a-aem.bb` is a good example. Some FVPs must be downloaded separately as they need an account on Arm's website. 59 60If `FVP_PROVIDER` is not set then it is assumed that `FVP_EXE` is installed on the host already. 61 62### `FVP_BINDIR` 63 64Optional parameter to configure the path of the FVP binary. For example, `fvp-base` uses path from the build host by default. This path can be customized by configuring like below. 65 66``` 67FVP_BINDIR ?= "utilities/fvp/usr/bin" 68``` 69 70Potential use case for this parameter configuration is to execute `runfvp` script without the need for bitbake environment initialization. 71 72### `FVP_CONFIG` 73 74Parameters passed to the FVP with the `--parameter`/`-C` option. These are expressed as variable flags so individual parameters can be altered easily. For example: 75 76``` 77FVP_CONFIG[bp.flashloader0.fname] = "fip-fvp.bin" 78``` 79 80### `FVP_DATA` 81 82Specify raw data to load at the specified address, passed to the FVP with the `--data` option. This is a space-separated list of parameters in the format `[INST=]FILE@[MEMSPACE:]ADDRESS`. For example: 83 84``` 85FVP_DATA = "cluster0.cpu0=Image@0x80080000 \ 86 cluster0.cpu0=fvp-base-revc.dtb@0x83000000" 87``` 88 89### `FVP_APPLICATIONS` 90 91Applications to load on the cores, passed to the FVP with the `--application` option. These are expressed as variable flags with the flag name being the instance and flag value the filename, for example: 92 93``` 94FVP_APPLICATIONS[cluster0] = "linux-system.axf" 95``` 96 97Note that symbols are not allowed in flag names, so if you need to use a wildcard in the instance then you'll need to use `FVP_EXTRA_ARGS` and `--application` directly. 98 99### `FVP_TERMINALS` 100 101Map hardware serial ports to abstract names. For example the `FVP_Base_RevC-2xAEMvA` FVP exposes four serial ports, `terminal_0` to `terminal_3`. Typically only `terminal_0` is used in the `fvp-base` machine so this can be named `"Console"` and the others `""`. When runfvp starts terminals it will only start named serial ports, so instead of opening four windows where only one is useful, it will only open one. 102 103For example: 104``` 105FVP_TERMINALS[bp.terminal_0] = "Console" 106FVP_TERMINALS[bp.terminal_1] = "" 107FVP_TERMINALS[bp.terminal_2] = "" 108FVP_TERMINALS[bp.terminal_3] = "" 109``` 110 111### `FVP_CONSOLES` 112 113This specifies what serial ports can be used in oeqa tests, along with an alias to be used in the test cases. Note that the values have to be the FVP identifier but without the board prefix, for example: 114``` 115FVP_CONSOLES[default] = "terminal_0" 116FVP_CONSOLES[tf-a] = "s_terminal_0" 117``` 118 119The 'default' console is also used when `--console` is passed to runfvp. 120 121### `FVP_EXTRA_ARGS` 122 123Arbitrary extra arguments that are passed directly to the FVP. For example: 124 125``` 126FVP_EXTRA_ARGS = "--simlimit 60" 127``` 128 129### `FVP_ENV_PASSTHROUGH` 130 131The FVP is launched with an isolated set of environment variables. Add the name of a Bitbake variable to this list to pass it through to the FVP environment. For example: 132 133``` 134FVP_ENV_PASSTHROUGH = "ARMLMD_LICENSE_FILE FM_TRACE_PLUGINS" 135``` 136 137 138[AEM]: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms/arm-ecosystem-models 139[FVP]: https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms 140[tmux]: https://tmux.github.io/ 141[INI]: https://docs.python.org/3/library/configparser.html 142